greprag 5.40.1 → 5.42.0

package/dist/archive/glyph-font.d.ts

@@ -0,0 +1,22 @@
+/** 8x8 monochrome bitmap font for the PNG archive renderer — printable
+ *  ASCII 32..126 (95 glyphs), one row byte per pixel row, LSB = leftmost.
+ *
+ *  Data: font8x8_basic by Daniel Hepper (public domain), itself based on
+ *  Marcel Sondaar / IBM public-domain VGA fonts.
+ *  https://github.com/dhepper/font8x8 — embedded as hex so the renderer
+ *  has ZERO runtime deps (Node's built-in zlib does PNG compression).
+ *
+ *  All 95 glyph bitmaps are pairwise distinct (verified at generation,
+ *  re-verified by tests/test-governed-compact.cjs), so pixel-level decode
+ *  back to text is unambiguous — the basis of the round-trip self-test.
+ *
+ *  GENERATED from font8x8_basic.h — regenerate rather than hand-edit.
+ */
+export declare const GLYPH_W = 8;
+export declare const GLYPH_H = 8;
+export declare const FIRST_CODE = 32;
+export declare const LAST_CODE = 126;
+/** Glyph rows (8 bytes) for a char code; null when outside 32..126. */
+export declare function glyphRows(code: number): number[] | null;
+export declare function codeForSignature(sigHex: string): number | null;
+export declare function signatureForRows(bytes: number[]): string;

package/dist/archive/glyph-font.js

@@ -0,0 +1,72 @@
+"use strict";
+// adr: adr/governed-compact.md
+/** 8x8 monochrome bitmap font for the PNG archive renderer — printable
+ *  ASCII 32..126 (95 glyphs), one row byte per pixel row, LSB = leftmost.
+ *
+ *  Data: font8x8_basic by Daniel Hepper (public domain), itself based on
+ *  Marcel Sondaar / IBM public-domain VGA fonts.
+ *  https://github.com/dhepper/font8x8 — embedded as hex so the renderer
+ *  has ZERO runtime deps (Node's built-in zlib does PNG compression).
+ *
+ *  All 95 glyph bitmaps are pairwise distinct (verified at generation,
+ *  re-verified by tests/test-governed-compact.cjs), so pixel-level decode
+ *  back to text is unambiguous — the basis of the round-trip self-test.
+ *
+ *  GENERATED from font8x8_basic.h — regenerate rather than hand-edit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAST_CODE = exports.FIRST_CODE = exports.GLYPH_H = exports.GLYPH_W = void 0;
+exports.glyphRows = glyphRows;
+exports.codeForSignature = codeForSignature;
+exports.signatureForRows = signatureForRows;
+exports.GLYPH_W = 8;
+exports.GLYPH_H = 8;
+exports.FIRST_CODE = 32;
+exports.LAST_CODE = 126;
+/** 95 glyphs, index = charCode - 32. 16 hex chars = 8 row bytes, top row
+ *  first; in each byte bit 0 (LSB) is the LEFTMOST pixel. */
+const FONT_HEX = [
+    '0000000000000000', '183c3c1818001800', '3636000000000000', '36367f367f363600', '0c3e031e301f0c00',
+    '006333180c666300', '1c361c6e3b336e00', '0606030000000000', '180c0606060c1800', '060c1818180c0600',
+    '00663cff3c660000', '000c0c3f0c0c0000', '00000000000c0c06', '0000003f00000000', '00000000000c0c00',
+    '6030180c06030100', '3e63737b6f673e00', '0c0e0c0c0c0c3f00', '1e33301c06333f00', '1e33301c30331e00',
+    '383c36337f307800', '3f031f3030331e00', '1c06031f33331e00', '3f3330180c0c0c00', '1e33331e33331e00',
+    '1e33333e30180e00', '000c0c00000c0c00', '000c0c00000c0c06', '180c0603060c1800', '00003f00003f0000',
+    '060c1830180c0600', '1e3330180c000c00', '3e637b7b7b031e00', '0c1e33333f333300', '3f66663e66663f00',
+    '3c66030303663c00', '1f36666666361f00', '7f46161e16467f00', '7f46161e16060f00', '3c66030373667c00',
+    '3333333f33333300', '1e0c0c0c0c0c1e00', '7830303033331e00', '6766361e36666700', '0f06060646667f00',
+    '63777f7f6b636300', '63676f7b73636300', '1c36636363361c00', '3f66663e06060f00', '1e3333333b1e3800',
+    '3f66663e36666700', '1e33070e38331e00', '3f2d0c0c0c0c1e00', '3333333333333f00', '33333333331e0c00',
+    '6363636b7f776300', '6363361c1c366300', '3333331e0c0c1e00', '7f6331184c667f00', '1e06060606061e00',
+    '03060c1830604000', '1e18181818181e00', '081c366300000000', '00000000000000ff', '0c0c180000000000',
+    '00001e303e336e00', '0706063e66663b00', '00001e3303331e00', '3830303e33336e00', '00001e333f031e00',
+    '1c36060f06060f00', '00006e33333e301f', '0706366e66666700', '0c000e0c0c0c1e00', '300030303033331e',
+    '070666361e366700', '0e0c0c0c0c0c1e00', '0000337f7f6b6300', '00001f3333333300', '00001e3333331e00',
+    '00003b66663e060f', '00006e33333e3078', '00003b6e66060f00', '00003e031e301f00', '080c3e0c0c2c1800',
+    '0000333333336e00', '00003333331e0c00', '0000636b7f7f3600', '000063361c366300', '00003333333e301f',
+    '00003f190c263f00', '380c0c070c0c3800', '1818180018181800', '070c0c380c0c0700', '6e3b000000000000',
+];
+/** Glyph rows (8 bytes) for a char code; null when outside 32..126. */
+function glyphRows(code) {
+    if (code < exports.FIRST_CODE || code > exports.LAST_CODE)
+        return null;
+    const hex = FONT_HEX[code - exports.FIRST_CODE];
+    const out = [];
+    for (let i = 0; i < 8; i++)
+        out.push(parseInt(hex.slice(i * 2, i * 2 + 2), 16));
+    return out;
+}
+/** Reverse map: 16-hex glyph signature -> char code. Built once, lazily. */
+let reverse = null;
+function codeForSignature(sigHex) {
+    if (!reverse) {
+        reverse = new Map();
+        for (let c = exports.FIRST_CODE; c <= exports.LAST_CODE; c++)
+            reverse.set(FONT_HEX[c - exports.FIRST_CODE], c);
+    }
+    return reverse.get(sigHex) ?? null;
+}
+function signatureForRows(bytes) {
+    return bytes.map((b) => (b & 0xff).toString(16).padStart(2, '0')).join('');
+}
+//# sourceMappingURL=glyph-font.js.map

package/dist/archive/glyph-font.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyph-font.js","sourceRoot":"","sources":["../../src/archive/glyph-font.ts"],"names":[],"mappings":"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"}

package/dist/archive/page-renderer.d.ts

@@ -0,0 +1,67 @@
+/** Page renderer — lays conversation text out on a fixed character grid and
+ *  rasterizes it with the embedded 8x8 font into 1568x1568 grayscale PNGs
+ *  (the Snapcompact pattern: text re-encoded as pixels reads back at ~3x
+ *  the token density via the vision path).
+ *
+ *  Geometry: 8x8 glyphs in 8x10 cells (2px leading for line separation) on
+ *  a 1568x1568 canvas -> 196 cols x 156 rows = 30,576 chars/page. That is
+ *  the deliberate middle of the Snapcompact reference range (6x10 ~40K
+ *  chars max-density vs 8x12 ~25K safe): font8x8 is a battle-tested VGA
+ *  face, far more legible to a vision model than a hand-authored 6x10.
+ *
+ *  Losslessness: chars outside printable ASCII are escaped to \\uXXXX (or
+ *  \\u{XXXXXX}) BEFORE layout, so every rendered char has a unique glyph and
+ *  pixel-level decode (decodePageText) reconstructs the grid exactly. The
+ *  round-trip self-test renders -> decodes -> compares grid text; it proves
+ *  the pixels carry the text losslessly. Long lines wrap at the column
+ *  boundary (wrap vs original-newline is not distinguished — acceptable for
+ *  a vision reader, noted in the ADR).
+ */
+export declare const PAGE_SIZE = 1568;
+export declare const CELL_W = 8;
+export declare const CELL_H = 10;
+export declare const COLS: number;
+export declare const ROWS: number;
+export declare const CHARS_PER_PAGE: number;
+/** Make text grid-safe and reversible: CRLF -> LF, tab -> \\t escape, any
+ *  char outside printable ASCII -> \\uXXXX / \\u{XXXXXX}. Output contains
+ *  only chars 32..126 plus newlines. */
+export declare function sanitizeForGrid(text: string): string;
+/** Sanitize text while re-mapping char-offset marks (turn starts) into the
+ *  sanitized offset space — escaping expands chars, so raw offsets drift. */
+export declare function sanitizeWithMarks<T extends {
+    charStart: number;
+}>(text: string, marks: T[]): {
+    sanitized: string;
+    marks: T[];
+};
+export interface GridRow {
+    /** Exactly COLS chars (space-padded). */
+    text: string;
+    /** Char offset of this row's first char in the sanitized source text. */
+    charStart: number;
+}
+/** Split sanitized text into grid rows: newline-separated lines, each
+ *  hard-wrapped at COLS. Rows are space-padded to exactly COLS chars. */
+export declare function layoutRows(sanitized: string, cols?: number): GridRow[];
+export interface RenderedPage {
+    png: Buffer;
+    /** The exact grid text on this page: ROWS lines of COLS chars. */
+    gridText: string;
+    charStart: number;
+    charEnd: number;
+}
+/** Rasterize one page of grid rows (up to ROWS) into a PNG. A full page is
+ *  1568x1568; the final partial page is only as tall as its rows, so its
+ *  grid text and its pixels stay in exact 1:1 correspondence (the round-trip
+ *  gate compares them) and the file carries no blank padding. */
+export declare function renderPage(pageRows: GridRow[], cols?: number, rows?: number): RenderedPage;
+/** Paginate grid rows into page-sized groups. */
+export declare function paginate(rowsIn: GridRow[], rowsPerPage?: number): GridRow[][];
+/** Read the grid text back out of a rendered page PNG by matching each
+ *  cell's 8x8 pixel block against the font table. Unknown signatures decode
+ *  as the Unicode replacement char so a corruption is loud, not silent. */
+export declare function decodePageText(png: Buffer, cols?: number): string;
+/** Render -> decode -> compare. Returns null when lossless, else a
+ *  description of the first mismatch. */
+export declare function verifyRoundTrip(page: RenderedPage): string | null;

package/dist/archive/page-renderer.js

@@ -0,0 +1,197 @@
+"use strict";
+// adr: adr/governed-compact.md
+/** Page renderer — lays conversation text out on a fixed character grid and
+ *  rasterizes it with the embedded 8x8 font into 1568x1568 grayscale PNGs
+ *  (the Snapcompact pattern: text re-encoded as pixels reads back at ~3x
+ *  the token density via the vision path).
+ *
+ *  Geometry: 8x8 glyphs in 8x10 cells (2px leading for line separation) on
+ *  a 1568x1568 canvas -> 196 cols x 156 rows = 30,576 chars/page. That is
+ *  the deliberate middle of the Snapcompact reference range (6x10 ~40K
+ *  chars max-density vs 8x12 ~25K safe): font8x8 is a battle-tested VGA
+ *  face, far more legible to a vision model than a hand-authored 6x10.
+ *
+ *  Losslessness: chars outside printable ASCII are escaped to \\uXXXX (or
+ *  \\u{XXXXXX}) BEFORE layout, so every rendered char has a unique glyph and
+ *  pixel-level decode (decodePageText) reconstructs the grid exactly. The
+ *  round-trip self-test renders -> decodes -> compares grid text; it proves
+ *  the pixels carry the text losslessly. Long lines wrap at the column
+ *  boundary (wrap vs original-newline is not distinguished — acceptable for
+ *  a vision reader, noted in the ADR).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHARS_PER_PAGE = exports.ROWS = exports.COLS = exports.CELL_H = exports.CELL_W = exports.PAGE_SIZE = void 0;
+exports.sanitizeForGrid = sanitizeForGrid;
+exports.sanitizeWithMarks = sanitizeWithMarks;
+exports.layoutRows = layoutRows;
+exports.renderPage = renderPage;
+exports.paginate = paginate;
+exports.decodePageText = decodePageText;
+exports.verifyRoundTrip = verifyRoundTrip;
+const glyph_font_1 = require("./glyph-font");
+const png_codec_1 = require("./png-codec");
+exports.PAGE_SIZE = 1568;
+exports.CELL_W = glyph_font_1.GLYPH_W; // 8
+exports.CELL_H = 10; // 8px glyph + 2px leading
+exports.COLS = Math.floor(exports.PAGE_SIZE / exports.CELL_W); // 196
+exports.ROWS = Math.floor(exports.PAGE_SIZE / exports.CELL_H); // 156
+exports.CHARS_PER_PAGE = exports.COLS * exports.ROWS; // 30,576
+const BG = 255; // white
+const FG = 0; // black
+// ---------- Text sanitation ---------------------------------------------------
+/** Make text grid-safe and reversible: CRLF -> LF, tab -> \\t escape, any
+ *  char outside printable ASCII -> \\uXXXX / \\u{XXXXXX}. Output contains
+ *  only chars 32..126 plus newlines. */
+function sanitizeForGrid(text) {
+    const out = [];
+    for (const ch of text.replace(/\r\n/g, '\n').replace(/\r/g, '\n')) {
+        const code = ch.codePointAt(0);
+        if (ch === '\n') {
+            out.push('\n');
+        }
+        else if (ch === '\t') {
+            out.push('\\t');
+        }
+        else if (code >= 32 && code <= 126) {
+            out.push(ch);
+        }
+        else if (code <= 0xffff) {
+            out.push('\\u' + code.toString(16).padStart(4, '0'));
+        }
+        else {
+            out.push('\\u{' + code.toString(16) + '}');
+        }
+    }
+    return out.join('');
+}
+/** Sanitize text while re-mapping char-offset marks (turn starts) into the
+ *  sanitized offset space — escaping expands chars, so raw offsets drift. */
+function sanitizeWithMarks(text, marks) {
+    const sortedMarks = [...marks].sort((a, b) => a.charStart - b.charStart);
+    const pieces = [];
+    const remapped = [];
+    let prevRaw = 0;
+    let sanitizedLen = 0;
+    for (const mark of sortedMarks) {
+        const piece = sanitizeForGrid(text.slice(prevRaw, mark.charStart));
+        pieces.push(piece);
+        sanitizedLen += piece.length;
+        remapped.push({ ...mark, charStart: sanitizedLen });
+        prevRaw = mark.charStart;
+    }
+    pieces.push(sanitizeForGrid(text.slice(prevRaw)));
+    return { sanitized: pieces.join(''), marks: remapped };
+}
+/** Split sanitized text into grid rows: newline-separated lines, each
+ *  hard-wrapped at COLS. Rows are space-padded to exactly COLS chars. */
+function layoutRows(sanitized, cols = exports.COLS) {
+    const rows = [];
+    let offset = 0;
+    for (const line of sanitized.split('\n')) {
+        if (line.length === 0) {
+            rows.push({ text: ' '.repeat(cols), charStart: offset });
+        }
+        else {
+            for (let i = 0; i < line.length; i += cols) {
+                const slice = line.slice(i, i + cols);
+                rows.push({ text: slice.padEnd(cols, ' '), charStart: offset + i });
+            }
+        }
+        offset += line.length + 1; // + newline
+    }
+    return rows;
+}
+/** Rasterize one page of grid rows (up to ROWS) into a PNG. A full page is
+ *  1568x1568; the final partial page is only as tall as its rows, so its
+ *  grid text and its pixels stay in exact 1:1 correspondence (the round-trip
+ *  gate compares them) and the file carries no blank padding. */
+function renderPage(pageRows, cols = exports.COLS, rows = exports.ROWS) {
+    const rowCount = Math.max(1, Math.min(pageRows.length, rows));
+    const width = cols * exports.CELL_W;
+    const height = rowCount * exports.CELL_H;
+    const pixels = Buffer.alloc(width * height, BG);
+    for (let r = 0; r < Math.min(pageRows.length, rowCount); r++) {
+        const row = pageRows[r];
+        for (let c = 0; c < cols; c++) {
+            const glyph = (0, glyph_font_1.glyphRows)(row.text.charCodeAt(c));
+            if (!glyph)
+                continue; // space stays background; out-of-range cannot occur post-sanitize
+            const px = c * exports.CELL_W;
+            const py = r * exports.CELL_H;
+            for (let gy = 0; gy < glyph_font_1.GLYPH_H; gy++) {
+                const bits = glyph[gy];
+                if (bits === 0)
+                    continue;
+                const base = (py + gy) * width + px;
+                for (let gx = 0; gx < glyph_font_1.GLYPH_W; gx++) {
+                    if (bits & (1 << gx))
+                        pixels[base + gx] = FG;
+                }
+            }
+        }
+    }
+    const img = { width, height, pixels };
+    const charStart = pageRows.length ? pageRows[0].charStart : 0;
+    const last = pageRows[pageRows.length - 1];
+    const charEnd = last ? last.charStart + last.text.trimEnd().length : charStart;
+    return {
+        png: (0, png_codec_1.encodePng)(img),
+        gridText: pageRows.map((r) => r.text).join('\n'),
+        charStart,
+        charEnd,
+    };
+}
+/** Paginate grid rows into page-sized groups. */
+function paginate(rowsIn, rowsPerPage = exports.ROWS) {
+    const pages = [];
+    for (let i = 0; i < rowsIn.length; i += rowsPerPage) {
+        pages.push(rowsIn.slice(i, i + rowsPerPage));
+    }
+    return pages;
+}
+// ---------- Pixel-level decode (round-trip self-test) ---------------------------
+/** Read the grid text back out of a rendered page PNG by matching each
+ *  cell's 8x8 pixel block against the font table. Unknown signatures decode
+ *  as the Unicode replacement char so a corruption is loud, not silent. */
+function decodePageText(png, cols = exports.COLS) {
+    const img = (0, png_codec_1.decodePng)(png);
+    const rows = Math.floor(img.height / exports.CELL_H);
+    const usableCols = Math.min(cols, Math.floor(img.width / exports.CELL_W));
+    const lines = [];
+    for (let r = 0; r < rows; r++) {
+        const chars = [];
+        for (let c = 0; c < usableCols; c++) {
+            const bytes = [];
+            for (let gy = 0; gy < glyph_font_1.GLYPH_H; gy++) {
+                let b = 0;
+                const base = (r * exports.CELL_H + gy) * img.width + c * exports.CELL_W;
+                for (let gx = 0; gx < glyph_font_1.GLYPH_W; gx++) {
+                    if (img.pixels[base + gx] < 128)
+                        b |= 1 << gx;
+                }
+                bytes.push(b);
+            }
+            const code = (0, glyph_font_1.codeForSignature)((0, glyph_font_1.signatureForRows)(bytes));
+            chars.push(code === null ? '�' : String.fromCharCode(code));
+        }
+        lines.push(chars.join(''));
+    }
+    return lines.join('\n');
+}
+/** Render -> decode -> compare. Returns null when lossless, else a
+ *  description of the first mismatch. */
+function verifyRoundTrip(page) {
+    const decoded = decodePageText(page.png);
+    if (decoded === page.gridText)
+        return null;
+    const a = page.gridText;
+    const b = decoded;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        if (a[i] !== b[i]) {
+            return `mismatch at char ${i}: rendered ${JSON.stringify(a[i])} decoded ${JSON.stringify(b[i])}`;
+        }
+    }
+    return `length mismatch: rendered ${a.length} decoded ${b.length}`;
+}
+//# sourceMappingURL=page-renderer.js.map

package/dist/archive/page-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-renderer.js","sourceRoot":"","sources":["../../src/archive/page-renderer.ts"],"names":[],"mappings":"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"}

package/dist/archive/png-codec.d.ts

@@ -0,0 +1,21 @@
+/** Minimal PNG encoder/decoder for the archive renderer — 8-bit grayscale
+ *  only, zero dependencies (Node's built-in zlib supplies DEFLATE; PNG's
+ *  IDAT is a zlib stream).
+ *
+ *  Encode writes filter type 0 (None) on every scanline — glyph bitmaps
+ *  deflate well without prediction and it keeps decode trivial. Decode
+ *  handles all five standard filters anyway, so files re-saved by other
+ *  tools still round-trip.
+ */
+export interface GrayImage {
+    width: number;
+    height: number;
+    /** Row-major, one byte per pixel, 0 = black .. 255 = white. */
+    pixels: Buffer;
+}
+export declare function crc32(buf: Buffer): number;
+/** Encode an 8-bit grayscale image as a PNG buffer. */
+export declare function encodePng(img: GrayImage): Buffer;
+/** Decode an 8-bit grayscale PNG produced by encodePng (or equivalent).
+ *  Throws on anything that isn't a non-interlaced 8-bit grayscale PNG. */
+export declare function decodePng(buf: Buffer): GrayImage;

package/dist/archive/png-codec.js

@@ -0,0 +1,197 @@
+"use strict";
+// adr: adr/governed-compact.md
+/** Minimal PNG encoder/decoder for the archive renderer — 8-bit grayscale
+ *  only, zero dependencies (Node's built-in zlib supplies DEFLATE; PNG's
+ *  IDAT is a zlib stream).
+ *
+ *  Encode writes filter type 0 (None) on every scanline — glyph bitmaps
+ *  deflate well without prediction and it keeps decode trivial. Decode
+ *  handles all five standard filters anyway, so files re-saved by other
+ *  tools still round-trip.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crc32 = crc32;
+exports.encodePng = encodePng;
+exports.decodePng = decodePng;
+const zlib = __importStar(require("zlib"));
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+// ---------- CRC32 (PNG polynomial) ------------------------------------------
+let crcTable = null;
+function getCrcTable() {
+    if (crcTable)
+        return crcTable;
+    crcTable = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        crcTable[n] = c >>> 0;
+    }
+    return crcTable;
+}
+function crc32(buf) {
+    const table = getCrcTable();
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++) {
+        c = table[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+// ---------- Encode -----------------------------------------------------------
+function chunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const typeAndData = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(typeAndData), 0);
+    return Buffer.concat([len, typeAndData, crc]);
+}
+/** Encode an 8-bit grayscale image as a PNG buffer. */
+function encodePng(img) {
+    const { width, height, pixels } = img;
+    if (pixels.length !== width * height) {
+        throw new Error(`pixel buffer ${pixels.length} != ${width}x${height}`);
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 0; // color type: grayscale
+    ihdr[10] = 0; // compression
+    ihdr[11] = 0; // filter method
+    ihdr[12] = 0; // no interlace
+    // Raw scanlines: filter byte 0 + row pixels.
+    const raw = Buffer.alloc(height * (width + 1));
+    for (let y = 0; y < height; y++) {
+        raw[y * (width + 1)] = 0;
+        pixels.copy(raw, y * (width + 1) + 1, y * width, (y + 1) * width);
+    }
+    const idat = zlib.deflateSync(raw, { level: 9 });
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        chunk('IHDR', ihdr),
+        chunk('IDAT', idat),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+}
+// ---------- Decode -----------------------------------------------------------
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    if (pb <= pc)
+        return b;
+    return c;
+}
+/** Decode an 8-bit grayscale PNG produced by encodePng (or equivalent).
+ *  Throws on anything that isn't a non-interlaced 8-bit grayscale PNG. */
+function decodePng(buf) {
+    if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new Error('not a PNG (bad signature)');
+    }
+    let width = 0;
+    let height = 0;
+    const idatParts = [];
+    let off = 8;
+    while (off + 8 <= buf.length) {
+        const len = buf.readUInt32BE(off);
+        const type = buf.toString('ascii', off + 4, off + 8);
+        const data = buf.subarray(off + 8, off + 8 + len);
+        if (type === 'IHDR') {
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            const bitDepth = data[8];
+            const colorType = data[9];
+            const interlace = data[12];
+            if (bitDepth !== 8 || colorType !== 0 || interlace !== 0) {
+                throw new Error(`unsupported PNG (bitDepth=${bitDepth} colorType=${colorType} interlace=${interlace})`);
+            }
+        }
+        else if (type === 'IDAT') {
+            idatParts.push(data);
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        off += 8 + len + 4; // len + type + data + crc
+    }
+    if (!width || !height)
+        throw new Error('PNG missing IHDR');
+    if (idatParts.length === 0)
+        throw new Error('PNG missing IDAT');
+    const raw = zlib.inflateSync(Buffer.concat(idatParts));
+    const stride = width + 1;
+    if (raw.length < height * stride) {
+        throw new Error(`PNG data short: ${raw.length} < ${height * stride}`);
+    }
+    const pixels = Buffer.alloc(width * height);
+    for (let y = 0; y < height; y++) {
+        const filter = raw[y * stride];
+        const rowIn = raw.subarray(y * stride + 1, y * stride + 1 + width);
+        const rowOut = pixels.subarray(y * width, (y + 1) * width);
+        for (let x = 0; x < width; x++) {
+            const a = x > 0 ? rowOut[x - 1] : 0; // left
+            const b = y > 0 ? pixels[(y - 1) * width + x] : 0; // up
+            const c = x > 0 && y > 0 ? pixels[(y - 1) * width + x - 1] : 0; // up-left
+            let v;
+            switch (filter) {
+                case 0:
+                    v = rowIn[x];
+                    break;
+                case 1:
+                    v = rowIn[x] + a;
+                    break;
+                case 2:
+                    v = rowIn[x] + b;
+                    break;
+                case 3:
+                    v = rowIn[x] + ((a + b) >> 1);
+                    break;
+                case 4:
+                    v = rowIn[x] + paeth(a, b, c);
+                    break;
+                default: throw new Error(`unsupported PNG filter ${filter} on row ${y}`);
+            }
+            rowOut[x] = v & 0xff;
+        }
+    }
+    return { width, height, pixels };
+}
+//# sourceMappingURL=png-codec.js.map

package/dist/archive/png-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"png-codec.js","sourceRoot":"","sources":["../../src/archive/png-codec.ts"],"names":[],"mappings":"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"}

package/dist/archive/transcript-extract.d.ts

@@ -0,0 +1,39 @@
+/** Transcript extraction for the PNG archive — JSONL -> flat conversation
+ *  text with turn-numbered section headers.
+ *
+ *  Main chain only: sidechain (subagent) entries are skipped — the archive
+ *  is the record of THIS conversation, which is what compaction is about to
+ *  summarize away. A "turn" increments on each real user message (one with
+ *  text content, not a tool_result carrier), matching the turn notion used
+ *  across the hook layer.
+ *
+ *  Section headers (`=== T<n> USER ===` etc.) give the vision model anchors
+ *  to scan for, and give the indexer the char offsets it needs to stamp a
+ *  turn range onto every rendered page.
+ */
+export interface TurnMark {
+    turn: number;
+    /** Char offset of the turn's first section header in the extracted text. */
+    charStart: number;
+}
+export interface ExtractedTranscript {
+    /** Flat conversation text (pre-sanitize — may contain any unicode). */
+    text: string;
+    /** Ascending char offsets where each turn begins. */
+    turnMarks: TurnMark[];
+    /** Total turns seen (= turnMarks.length). */
+    turns: number;
+}
+/** Extract the main-chain conversation from a transcript JSONL string. */
+export declare function extractConversation(jsonl: string): ExtractedTranscript;
+/** File wrapper. Returns null when the transcript can't be read. */
+export declare function extractTranscriptFile(transcriptPath: string): ExtractedTranscript | null;
+/** Turn range [first, last] overlapping a char window. turnMarks must be
+ *  ascending and in the SAME offset space as the window (callers re-map
+ *  marks through sanitizeWithMarks before paginating). A turn spans from
+ *  its mark to the next mark (the last turn runs to infinity). Content
+ *  before the first mark (rare T0 preamble) reports as turn 0. */
+export declare function turnRangeForWindow(marks: TurnMark[], charStart: number, charEnd: number): {
+    turnStart: number;
+    turnEnd: number;
+};