@prometheus-ai/snapcompact 0.5.8

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.5.5] - 2026-06-14
+
+### Breaking Changes
+
+- Renamed every export to drop the `snapcompact`/`Snapcompact`/`SNAPCOMPACT_` qualifier — the package is meant to be consumed via `import * as snapcompact from "@prometheus-ai/snapcompact"`. Functions: `snapcompactCompact` → `compact`, `renderSnapcompactFrame` → `render`, `snapcompactGeometry` → `geometry`, `normalizeForSnapcompact` → `normalize`, `serializeSnapcompactConversation` → `serializeConversation`, `snapcompactImages` → `images`, `getPreservedSnapcompactArchive` → `getPreservedArchive`, `isSnapcompactShape` → `isShape`, `resolveSnapcompactShape` → `resolveShape`, `createSnapcompactFileOps` → `createFileOps`, `computeSnapcompactFileLists` → `computeFileLists`, `upsertSnapcompactFileOperations` → `upsertFileOperations`. Types: `SnapcompactShape` → `Shape`, `SnapcompactFrame` → `Frame`, `SnapcompactArchive` → `Archive`, `SnapcompactGeometry` → `Geometry`, `SnapcompactOptions` → `Options`, `SnapcompactSerializeOptions` → `SerializeOptions`, `SnapcompactFileOperations` → `FileOperations`, `SnapcompactCompactionDetails`/`Preparation`/`Result` → `CompactionDetails`/`CompactionPreparation`/`CompactionResult`, `SnapcompactConvertToLlm` → `ConvertToLlm`. Constants: `SNAPCOMPACT_X` → `X` (`SHAPES`, `FRAME_SIZE`, `MAX_FRAMES`, `FRAME_TOKEN_ESTIMATE`, `PRESERVE_KEY`, `TOOL_RESULT_MAX_CHARS`, `TOOL_ARG_MAX_CHARS`, `TOOL_CALL_MAX_CHARS`, `TRUNCATE_HEAD_RATIO`, `DIM_ON`, `DIM_OFF`).
+- Changed `renderSnapcompactFrame` output from `png: Uint8Array` to `data: string` base64, requiring consumers to read frame payloads from `frame.data`
+
+### Added
+
+- Added two spacing-tuned frame variants to `SHAPE_VARIANTS`: `8on22-bw` (8x13 glyphs on a 22px pitch — extra line spacing) and `11on16-bw` (8x13 glyphs on an 11px advance — extra letter spacing). Both pin the indexed `stretch: false` path, so the native renderer draws natural-size glyphs on the padded cell box (the Rust path already advances by `cellWidth` and the new variants validate horizontal padding)
+- Added `SHAPE_VARIANTS`, the catalog of research-eval frame variants the native renderer reproduces faithfully (`8x8r`/`8x8u`/`6x6u`/`5x8` × `sent`/`bw`), with `ShapeVariantName`, `SHAPE_VARIANT_NAMES`, and the `isShapeVariantName` guard
+- `resolveShape(api, variant?)` now accepts an explicit variant name (or `"auto"`); forced variants keep their geometry but are re-priced for the target provider's image billing (token estimate and OpenAI `original` detail hint)
+- Added the six research-eval winning frame variants to `SHAPE_VARIANTS`: `6x12-dim` (Claude fable), `8x13-bw` (Opus), `8on16-bw` (GPT grid runner-up), `doc-8on16-bw` (GPT), `doc-8on16-sent` (GLM), and `doc-8on16-sent-dim` (Gemini/Kimi), backed by new `Shape` fields `stretch` (disable Lanczos stretch: natural glyphs on a larger cell pitch), `columns` (two word-wrapped newspaper columns), `stopwordDim`, and the X.org `6x12`/`8x13` fonts
+- Added `dimStopwords()`, which prints high-frequency function words in dim ink via zero-width markers (skipping spans that are already dim), and `wrap()`, the greedy word-wrap used to typeset doc-layout pages; `geometry`/`render`/`renderMany`/`frames`/`compact` understand doc shapes (wrap once, paginate into `2 * rows`-line pages), and compaction frames persist `columns`/`stopwordDim` for mixed-shape detection
+- `resolveShape` now takes a `ShapeTarget` (`{ api, id }` — a Prometheus AI `Model` works as-is) and detects the ideal shape from the **model id**, not just the wire API: a Claude routed through Vertex or an OpenAI-compatible gateway keeps its Claude shape, with billing still priced by the API family actually carrying the request. `idealShapeVariant(modelId)` exposes the model-line table; unmeasured models fall back to the API family's winner
+- `resolveShape` now also resolves an ideal **frame size** per model line, and billing estimates come from verified per-family formulas instead of flat 1568px constants: Anthropic bills 28px patches capped at 4,784 visual tokens (+5% margin), Gemini 3.x bills a fixed 1,120-token `media_resolution` budget per image at any pixel size, and OpenAI bills 32px patches × 1.2 under the 10,000-patch `detail: "original"` budget. High-res Claude lines (Opus 4.7+, Fable, Mythos — native 2576px-edge ingestion) get 1932px frames (same recall and cost, a third fewer frames); Gemini gets 2048px frames (+70% chars per frame at the same bill); GPT and Kimi stay at 1568px (area-proportional billing and a model-side 1792px processor cap, respectively). `idealShapeVariant` now returns an `IdealShape` (`{ variant, frameSize? }`)
+- Added per-provider image-count budgets: `PROVIDER_IMAGE_BUDGETS`, `DEFAULT_PROVIDER_IMAGE_BUDGET`, `providerImageBudget()`, and `providerFrameBudget()` (the image budget clamped to `MAX_FRAMES`). OpenRouter is capped at its measured hard limit of 8 images per request (excess images are silently dropped with no error); unknown providers get a safe floor of 5
+- Added `Archive.textTail`: archive content past the frame budget is no longer dropped — `compact()` stops rendering at the budget and keeps the newest unframed slice as verbatim text on the summary (capped at two frame capacities with middle elision, counted into `truncatedChars` when elided). The tail persists in `preserveData` and is folded back into frames by the next compaction
+- Added `renderMany()` for paging arbitrary text into snapcompact PNG frames as LLM image blocks, and `frames()` for predicting the frame count without rendering
+- Added new serialization options `toolResultMaxChars`, `toolArgMaxChars`, `toolCallMaxChars`, `truncateHeadRatio`, and `dimToolResults` to `snapcompactCompact`/`serializeSnapcompactConversation` so callers can tune how tool results and arguments are archived
+- Added exported default constants `SNAPCOMPACT_TOOL_RESULT_MAX_CHARS`, `SNAPCOMPACT_TOOL_ARG_MAX_CHARS`, `SNAPCOMPACT_TOOL_CALL_MAX_CHARS`, and `SNAPCOMPACT_TRUNCATE_HEAD_RATIO` for reuse when configuring truncation limits
+- Added provider-specific snapcompact frame-shape presets and shape helpers (`SNAPCOMPACT_SHAPES`, `resolveSnapcompactShape`, `isSnapcompactShape`) so callers can consistently select validated image-frame geometry for archive renders
+- Added `file-operations.md` and `snapcompact-summary.md` prompts to preserve file-read/write context and frame metadata in the compaction prompt flow
+- Added a full `packages/snapcompact/research` experiment and visualization suite for running snapcompact SQuAD studies, provider probes, and activation-style analyses
+- Added package-level TypeScript exports so Prometheus can stage typed access to snapcompact APIs before runtime wiring is enabled
+- Restored `@prometheus-ai/snapcompact` as a private staging package, including bitmap-frame rendering helpers, archive helpers, and the local `snapcompactCompact()` strategy.
+
+### Changed
+
+- **Changed the per-provider default shapes to the spacing-tuned cells.** The previous shapes were tuned on the SQuAD *prose* eval, where dense cells won; a new tool-result legibility benchmark (`research/toolbench.py` — real `search`/`read`/`find` output with structure-sensitive QA) showed the prose-era density erases the line numbers and indentation that code/search output depends on. Anthropic moves from `6x12-dim` to `11on16-bw` (opus-4.8 f1 .806 vs .755 for plain `8on16-bw` and .351 for `6x12-dim`, which fell below the OCR ~16px/char floor and abstained); OpenAI and Google move to `8on22-bw` (gemini-3.5-flash f1 .934 vs .807 for `8on16-bw` and .287 for `doc-8on16-sent-dim`; same leading win on gpt-5.5/gpt-5.4-mini). Kimi and GLM keep their measured `8on16-bw`. The bigger cells pack fewer chars per frame, so inline frame-swapping now breaks even at a larger tool-result size
+- `serializeConversation` now skips tool call/result pairs whose result is flagged contextually useless (`useless: true`, non-error), so archived frames stop carrying zero-match searches and timed-out waits
+- Frames are no longer padded to a square: the native renderer clips each PNG's height to the text rows actually printed, so a partially filled frame (typically the newest) bills only the pixel rows it uses
+- **Changed the OpenAI default shape from `6x6u-sent` to `8on16-bw`.** A production-regime mono eval (gpt-5.5, the full 800k-char SQuAD flow in one request, n=50) scored the old dense default f1 .602 vs .851 for `8on16-bw` rendered by the production pipeline, at near-equal total cost (the dense cells burned the frame savings on reasoning tokens); chunked exp14 had already scored `8on16-bw` .906. `SHAPES.openaiDense` is renamed to `SHAPES.openai`
+- **Changed the Google default shape from `8x8r-sent` to `doc-8on16-sent-dim`.** Production-rendered mono eval on gemini-3.5-flash (400k chars, one request, n=25): f1 .900 vs .853 for the repeated grid at lower cost, agreeing with the chunked round-2 winner
+- **Changed the Anthropic default shape from `8x8r-bw` to `6x12-dim`.** Production mono eval on claude-fable (400k chars, one request, n=25): f1 .840 vs .877 for the repeated grid — within noise — at 37% lower cost (12 frames instead of 21 per 400k chars), with clean completions in every probe; opus reads the same trade (.800 vs .833 at 42% lower cost)
+- `normalize()` now keeps line structure: whitespace runs containing a line break collapse to `NEWLINE_GLYPH` (U+2588 FULL BLOCK, drawn by the native renderer as a pitch-black cell one character wide) instead of a plain space; leading/trailing breaks are trimmed, and the frame-reading prompt explains the marker
+- `normalize()` now skips characters the fonts cannot render instead of printing `?` blanks: whole ANSI escape sequences are stripped, and bare control characters, zero-width format characters (ZWSP, BOM, directional marks), combining marks, and lone surrogates are dropped without occupying a cell; `?` remains the fallback for unsupported graphic characters only
+- Changed truncation in archived tool output to keep both the beginning and end of long text using a configurable head/tail ratio instead of a single hard cut
+- Changed tool-result text rendering so archived tool results are shown in dim gray ink by default and the summary prompt notes that dim text is archived tool output
+- Changed `RenderedFrame` visible-character accounting so `chars` no longer includes invisible dim-control markers
+- Changed the file-operations summary block to a single `<files>` tag: one grouped, prefix-folded directory tree with per-file `(Read)`/`(Write)`/`(RW)` markers, replacing the separate `<read-files>`/`<modified-files>` lists; `upsertSnapcompactFileOperations` takes the cumulative read set to distinguish `(RW)` from blind writes
+
+### Fixed
+
+- Fixed frame rendering at archive chunk boundaries to reopen dim spans when a chunk ends inside a dimmed tool-result segment
+- Fixed message serialization to strip user- and assistant-provided dim markers so only renderer-generated dim spans can be applied

package/README.md

@@ -0,0 +1,70 @@
+# @prometheus-ai/snapcompact
+
+Bitmap-frame context compression for vision-capable LLMs.
+
+Instead of asking an LLM to summarize discarded conversation history, snapcompact serializes it and renders the text into dense PNG frames of pixel-font glyphs that vision models read back directly. The whole pass is local and deterministic — no LLM call, no API key, no latency beyond rendering. Rasterization and PNG encoding happen in native code (`@prometheus-ai/natives`).
+
+Built for [prometheus](https://github.com/uttamtrivedi/Prometheus)'s compaction pipeline, but the rendering API works on arbitrary text.
+
+## How it works
+
+1. Discarded history is serialized to compact text (`serializeConversation`), with per-tool-result and per-argument character caps.
+2. Text is normalized for the bundled bitmap fonts (`normalize`): ANSI sequences stripped, whitespace collapsed, newline runs folded into a single full-block glyph so line structure survives.
+3. Pages of text are rasterized into PNG frames (`render` / `renderMany`). Frame width is fixed per shape; height hugs the rows actually printed, so a partially filled frame never bills blank pixel rows.
+4. Frames persist in the compaction entry's `preserveData` and are re-attached to the summary message on every context rebuild.
+
+Frame shapes are provider-aware, chosen by SQuAD recall evals (see `research/`) against real provider billing:
+
+| Reader | Default shape | Notes |
+| --- | --- | --- |
+| Anthropic | `6x12-dim` | X.org 6x12 glyphs, stopwords dimmed gray; high-res Claude lines get 1932px frames |
+| Google | `doc-8on16-sent-dim` @2048 | Two newspaper columns, sentence-hue ink; Gemini bills a fixed per-image budget, so larger frames are free chars |
+| OpenAI | `8on16-bw` | 8x13 glyphs on a patch-aligned 16px pitch, sent at `detail: "original"` |
+| Unknown | Anthropic shape | Per-provider image-count budgets guard against gateways that silently drop frames |
+
+`resolveShape({ api, id })` matches the model id, not just the wire API — a Claude routed through Vertex or OpenRouter keeps its Claude shape, priced for the gateway actually carrying the request.
+
+## Install
+
+```sh
+bun add @prometheus-ai/snapcompact
+```
+
+Ships TypeScript source directly (no build step); requires Bun ≥ 1.3.14.
+
+## Usage
+
+Render arbitrary text into LLM image blocks:
+
+```ts
+import { renderMany, frames, resolveShape } from "@prometheus-ai/snapcompact";
+
+const images = renderMany(longText, { model }); // ImageContent[], first page first
+const count = frames(longText, { model });      // frame count without rendering
+const shape = resolveShape(model);              // eval-optimal Shape for the reader
+```
+
+Run a full compaction pass over prepared messages:
+
+```ts
+import { compact } from "@prometheus-ai/snapcompact";
+
+const result = await compact(preparation, { model, maxFrames: 8 });
+// result.summary        — text summary with <files> operations block
+// result.preserveData   — frame archive, re-attachable via getPreservedArchive() + images()
+```
+
+## API surface
+
+- **Compaction**: `compact`, `CompactionPreparation`, `CompactionResult`, `getPreservedArchive`, `images`
+- **Rendering**: `render`, `renderMany`, `frames`, `geometry`
+- **Shapes**: `SHAPES`, `SHAPE_VARIANTS`, `resolveShape`, `idealShapeVariant`, `isShape`, `isShapeVariantName`
+- **Text**: `serializeConversation`, `normalize`, `dimStopwords`, `wrap`
+- **Budgets**: `providerImageBudget`, `providerFrameBudget`, `MAX_FRAMES`, `FRAME_TOKEN_ESTIMATE`
+- **File ops**: `createFileOps`, `computeFileLists`, `upsertFileOperations`
+
+## References
+
+- [Monorepo README](https://github.com/uttamtrivedi/Prometheus#readme)
+- [Compaction architecture](../../docs/compaction.md)
+- [CHANGELOG](./CHANGELOG.md)

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./snapcompact";

package/dist/types/snapcompact.d.ts

@@ -0,0 +1,523 @@
+/**
+ * Snapcompact compaction: archive conversation history as dense bitmap images.
+ *
+ * Instead of asking an LLM to summarize discarded history, the serialized
+ * conversation is rendered into PNG frames of pixel-font text that vision
+ * models read back directly, like an archivist at a snapcompact frame
+ * reader. Frames are `frameSize` wide; their height hugs the text rows
+ * actually printed, so a partially filled frame never bills blank rows.
+ *
+ * The frame shape is provider-aware. Original choices came from the SQuAD
+ * prose evals (`packages/snapcompact`, 200k-token monolithic runs); the
+ * spacing choices below come from the tool-result legibility bench
+ * (`research/toolbench.py`, real search/read/find output with structure QA),
+ * which exposed that the prose-tuned dense cells erase the line numbers and
+ * indentation that code/search output depends on:
+ *
+ * - **Anthropic** (`11on16-bw`): 8x13 glyphs on an 11px advance (extra
+ *   letter-spacing), black ink. On the tool-result bench, tracking the
+ *   readable cell beat plain `8on16-bw` (opus-4.8 f1 .806 vs .755) and far
+ *   beat the prior dense `6x12-dim` (.351, which fell below the OCR ~16px/char
+ *   floor and abstained). Opus 4.7+/Fable/Mythos ingest high-res natively
+ *   (2576px edge, 4,784 visual-token cap), so those lines get 1932px frames:
+ *   same bill, fewer frames. Older Claude lines downscale past 1568px.
+ * - **Google** (`8on22-bw` @2048): 8x13 glyphs on a 22px pitch (extra line
+ *   spacing), black ink. Leading lifted gemini-3.5-flash to f1 .934 vs .807
+ *   for `8on16-bw` and .287 for the prior `doc-8on16-sent-dim`. Gemini 3.x
+ *   bills a fixed `media_resolution` budget per image (default 1,120 tokens)
+ *   regardless of pixels, so the 2048px frame carries more chars at the same
+ *   bill.
+ * - **OpenAI** (`8on22-bw`): same leading win (gpt-5.5/gpt-5.4-mini). Patch
+ *   billing (32px × 1.2, 10k-patch budget at `detail: "original"`) is
+ *   area-proportional, so resolution cannot improve chars/$ — 1568 stays.
+ *   `detail: "high"` would downgrade (2,500-patch cap); `original` is sent.
+ * - **Unknown providers** default to the Anthropic shape. Gateways can
+ *   defeat any shape silently: OpenRouter enforces a per-model image cap
+ *   (measured: 8 images for glm-4.6v — frames past the cap are dropped with
+ *   no error, billed tokens plateau exactly at 8x frame cost). The same
+ *   frames routed direct to the vendor read fine (glm f1 .20 -> .78), so
+ *   `providerImageBudget` caps per-request images per provider (OpenRouter
+ *   8, unknown 5) and `compact()` keeps any archive overflow as a text tail
+ *   on the summary instead of rendering frames that would be dropped.
+ *
+ * The whole pass is local and deterministic — no LLM call, no API key, no
+ * latency beyond rendering. Rasterization and PNG encoding happen in native
+ * code (`renderSnapcompactPng` in `crates/prometheus-natives/src/snapcompact.rs`).
+ * Frames persist in the compaction entry's `preserveData` and are
+ * re-attached to the compaction summary message on every context rebuild.
+ */
+import type { Api, ImageContent, Message, Model } from "@prometheus-ai/ai";
+/** One eval-validated frame shape: font, cell, ink, repetition, and size. */
+export interface Shape {
+    /** Bundled font in the native renderer. */
+    font: "5x8" | "8x8" | "6x12" | "8x13";
+    /** Target cell advance in pixels; differing from the font's natural cell
+     *  renders via Lanczos stretch (anti-aliased RGB frame). */
+    cellWidth: number;
+    /** Target cell pitch in pixels. */
+    cellHeight: number;
+    /** `false` → glyphs drawn at natural size on the cell pitch (8on16);
+     *  `true`/`undefined` → legacy auto Lanczos stretch when cell ≠ natural. */
+    stretch?: boolean;
+    /** Ink: `sent` cycles six hues at sentence boundaries; `bw` is black. */
+    variant: "sent" | "bw";
+    /** Print stopwords in dim ink (research `dim`/`sent-dim` variants). */
+    stopwordDim?: boolean;
+    /** 1/undefined = row-major grid; 2 = two word-wrapped newspaper columns
+     *  (research `doc`). */
+    columns?: number;
+    /** Each text line is printed this many times; copies after the first sit
+     *  on a pale highlight band (redundancy coding). */
+    lineRepeat: number;
+    /** Frame edge in pixels. */
+    frameSize: number;
+    /** Per-frame billed-token estimate for the shape's target provider. */
+    frameTokenEstimate: number;
+    /** Resolution hint attached to frame images (OpenAI-only). */
+    imageDetail?: ImageContent["detail"];
+}
+/** Geometry half of a {@link Shape}: everything except provider billing. */
+export type ShapeGeometry = Omit<Shape, "frameTokenEstimate" | "imageDetail">;
+/**
+ * Frame variants exercised by the SQuAD evals in `research/` that the native
+ * renderer reproduces faithfully, keyed by their research names. Font codes:
+ * `8x8u` unscii square cell, `8x8r` unscii with every line printed twice
+ * (redundancy coding), `6x6u` unscii Lanczos-squeezed to 6x6 (densest
+ * readable cell), `5x8` the X.org legacy font on its 2576px frame, `6x12`
+ * and `8x13` the X.org misc fonts, `8on16` 8x13 glyphs on an 8x16 cell pitch
+ * (no stretch, extra leading), `8on22` the same glyphs on a 22px pitch (more
+ * leading), `11on16` the same glyphs on an 11px advance (more tracking),
+ * `doc-` prefixed shapes a two-column word-wrapped newspaper layout. Ink:
+ * `sent` cycles six hues at sentence boundaries, `bw` is plain black, `-dim`
+ * suffix prints stopwords in gray.
+ */
+export declare const SHAPE_VARIANTS: {
+    readonly "8x8r-bw": {
+        readonly font: "8x8";
+        readonly cellWidth: 8;
+        readonly cellHeight: 8;
+        readonly variant: "bw";
+        readonly lineRepeat: 2;
+        readonly frameSize: 1568;
+    };
+    readonly "8x8r-sent": {
+        readonly font: "8x8";
+        readonly cellWidth: 8;
+        readonly cellHeight: 8;
+        readonly variant: "sent";
+        readonly lineRepeat: 2;
+        readonly frameSize: 1568;
+    };
+    readonly "8x8u-bw": {
+        readonly font: "8x8";
+        readonly cellWidth: 8;
+        readonly cellHeight: 8;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "8x8u-sent": {
+        readonly font: "8x8";
+        readonly cellWidth: 8;
+        readonly cellHeight: 8;
+        readonly variant: "sent";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "6x6u-bw": {
+        readonly font: "8x8";
+        readonly cellWidth: 6;
+        readonly cellHeight: 6;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "6x6u-sent": {
+        readonly font: "8x8";
+        readonly cellWidth: 6;
+        readonly cellHeight: 6;
+        readonly variant: "sent";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "5x8-bw": {
+        readonly font: "5x8";
+        readonly cellWidth: 5;
+        readonly cellHeight: 8;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 2576;
+    };
+    readonly "5x8-sent": {
+        readonly font: "5x8";
+        readonly cellWidth: 5;
+        readonly cellHeight: 8;
+        readonly variant: "sent";
+        readonly lineRepeat: 1;
+        readonly frameSize: 2576;
+    };
+    readonly "6x12-dim": {
+        readonly font: "6x12";
+        readonly cellWidth: 6;
+        readonly cellHeight: 12;
+        readonly variant: "bw";
+        readonly stopwordDim: true;
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "8x13-bw": {
+        readonly font: "8x13";
+        readonly cellWidth: 8;
+        readonly cellHeight: 13;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "8on16-bw": {
+        readonly font: "8x13";
+        readonly cellWidth: 8;
+        readonly cellHeight: 16;
+        readonly stretch: false;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "8on22-bw": {
+        readonly font: "8x13";
+        readonly cellWidth: 8;
+        readonly cellHeight: 22;
+        readonly stretch: false;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "11on16-bw": {
+        readonly font: "8x13";
+        readonly cellWidth: 11;
+        readonly cellHeight: 16;
+        readonly stretch: false;
+        readonly variant: "bw";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "doc-8on16-bw": {
+        readonly font: "8x13";
+        readonly cellWidth: 8;
+        readonly cellHeight: 16;
+        readonly stretch: false;
+        readonly variant: "bw";
+        readonly columns: 2;
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "doc-8on16-sent": {
+        readonly font: "8x13";
+        readonly cellWidth: 8;
+        readonly cellHeight: 16;
+        readonly stretch: false;
+        readonly variant: "sent";
+        readonly columns: 2;
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+    readonly "doc-8on16-sent-dim": {
+        readonly font: "8x13";
+        readonly cellWidth: 8;
+        readonly cellHeight: 16;
+        readonly stretch: false;
+        readonly variant: "sent";
+        readonly stopwordDim: true;
+        readonly columns: 2;
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+    };
+};
+/** Research name of one renderable frame variant. */
+export type ShapeVariantName = keyof typeof SHAPE_VARIANTS;
+/** All variant names, in declaration order (for settings enums). */
+export declare const SHAPE_VARIANT_NAMES: readonly ShapeVariantName[];
+/** Runtime guard for variant names loaded from config. */
+export declare function isShapeVariantName(value: unknown): value is ShapeVariantName;
+/** Eval-validated shapes, keyed by the provider family they won on. */
+export declare const SHAPES: {
+    /** `11on16-bw`: 8x13 glyphs on an 11px advance (extra tracking), black ink.
+     *  Tool-result legibility bench (real search/read/find output, structure QA)
+     *  on opus-4.8: f1 .806 vs .755 for plain `8on16-bw` and .351 for the prior
+     *  `6x12-dim` default — letter-spacing the readable cell wins; the dense
+     *  6x12 was below the OCR ~16px/char floor and abstained. */
+    anthropic: Shape;
+    /** `8on22-bw`: 8x13 glyphs on a 22px pitch (extra leading), black ink.
+     *  Tool-result legibility bench on gemini-3.5-flash: f1 .934 vs .807 for
+     *  plain `8on16-bw` and .287 for the prior `doc-8on16-sent-dim`; the
+     *  line-spacing reduces row crowding so line numbers stay legible. */
+    google: Shape;
+    /** `8on22-bw`: 8x13 glyphs on a 22px pitch (extra leading), black ink.
+     *  Same line-spacing win for OpenAI; bench on gpt-5.5/gpt-5.4-mini showed
+     *  leading lifts recall on the readable cell over plain `8on16-bw`. */
+    openai: Shape;
+    /** Original 5x8 X.org shape (pre-shape-table sessions rendered this). */
+    legacy: Shape;
+};
+/** Runtime guard for shape overrides loaded from config or preserve data. */
+export declare function isShape(value: unknown): value is Shape;
+/** One model line's ideal format: variant plus an optional frame-size
+ *  override when the line reads larger frames at no extra cost. */
+export interface IdealShape {
+    variant: ShapeVariantName;
+    frameSize?: number;
+}
+/** Eval-ideal format for a model id, or undefined when unmeasured. */
+export declare function idealShapeVariant(modelId: string): IdealShape | undefined;
+/** What will read the frames: the wire API (billing) and model id (shape). */
+export interface ShapeTarget {
+    api?: Api;
+    id?: string;
+}
+/**
+ * Pick the frame shape for a reader. An explicit `variant` (anything but
+ * `"auto"`) forces that geometry; otherwise the model id selects the
+ * eval-winning shape — and frame size — for its model line, falling back to
+ * the API family's winner when the model is unmeasured. Billing (token
+ * estimate, detail hint) always follows the API family actually carrying
+ * the request, computed for the resolved frame size. Accepts a full Prometheus AI
+ * `Model` or any `{ api, id }` subset.
+ */
+export declare function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape;
+/** Legacy frame edge in pixels (the 5x8 shape's eval-validated size). New
+ *  shapes carry their own `frameSize`. */
+export declare const FRAME_SIZE = 2576;
+/** Maximum frames carried on a compaction entry. Oldest frames are dropped
+ *  first once the budget is exceeded (mirrors how iterative text summaries
+ *  fade the oldest detail). */
+export declare const MAX_FRAMES = 8;
+/** Conservative per-frame token estimate used for context budgeting
+ *  (upper bound across shapes: Anthropic bills 1568*1568/750 ≈ 3,278). */
+export declare const FRAME_TOKEN_ESTIMATE = 3300;
+/**
+ * Per-request image-count budgets by provider id. Routers and smaller
+ * providers enforce hard caps and silently DROP images past them (measured:
+ * OpenRouter caps at 8 — images 9+ vanish with no error and billed tokens
+ * plateau at 8x frame cost). First-party APIs allow far more; their values
+ * are conservative policy caps well under the measured hard limits
+ * (Anthropic 100, OpenAI 500, Gemini ~2500).
+ */
+export declare const PROVIDER_IMAGE_BUDGETS: Record<string, number>;
+/** Safe floor for unknown providers (strictest mainstream measured: Groq ~5). */
+export declare const DEFAULT_PROVIDER_IMAGE_BUDGET = 5;
+/** Per-request image budget for `provider`; unknown providers get the floor. */
+export declare function providerImageBudget(provider: string | undefined): number;
+/** Archive frame budget for `provider`: its image budget clamped to {@link MAX_FRAMES}. */
+export declare function providerFrameBudget(provider: string | undefined): number;
+/** Key under `CompactionEntry.preserveData` holding the frame archive. */
+export declare const PRESERVE_KEY = "snapcompact";
+/** One developed snapcompact frame: a base64 PNG plus its reading geometry. */
+export interface Frame {
+    /** Base64-encoded PNG. */
+    data: string;
+    mimeType: string;
+    /** Characters per row in the frame grid (per-column width on doc frames). */
+    cols: number;
+    /** Text rows in the frame grid (unique lines, not repeated copies). */
+    rows: number;
+    /** Characters actually printed onto this frame. */
+    chars: number;
+    /** Shape metadata (absent on legacy frames, which are 5x8 `sent`). */
+    font?: Shape["font"];
+    variant?: Shape["variant"];
+    lineRepeat?: number;
+    /** 2 on two-column doc frames; absent on row-major grid frames. */
+    columns?: number;
+    /** True when stopwords were printed in dim ink. */
+    stopwordDim?: boolean;
+    /** Resolution hint forwarded to the provider when re-attaching. */
+    detail?: ImageContent["detail"];
+}
+/** Frame archive persisted under `preserveData[PRESERVE_KEY]`. */
+export interface Archive {
+    /** Frames ordered oldest to newest. */
+    frames: Frame[];
+    /** Characters currently readable across all frames. */
+    totalChars: number;
+    /** Characters dropped so far to respect the frame budget. */
+    truncatedChars: number;
+    /** Most recent slice of archived history that exceeded the frame budget,
+     *  kept verbatim as normalized text (dim markers and newline glyphs
+     *  included). Shipped as plain text in the compaction summary and folded
+     *  back into frames by the next compaction. */
+    textTail?: string;
+}
+export interface Geometry {
+    /** Characters per row (per-column line width when `columns === 2`). */
+    cols: number;
+    rows: number;
+    /** Characters that fit one frame (nominal upper bound on doc shapes,
+     *  where real consumption is wrap-dependent). */
+    capacity: number;
+}
+export interface Options<TMessage = Message> extends SerializeOptions {
+    /** App-level message transformer (same contract as agent-core's `SummaryOptions.convertToLlm`). */
+    convertToLlm?: ConvertToLlm<TMessage>;
+    /** Model whose provider API selects the frame shape. */
+    model?: Pick<Model, "api">;
+    /** Caller-owned reasoning/thinking level metadata; currently preserved for compatibility. */
+    thinkingLevel?: unknown;
+    /** Explicit shape override; wins over `model`. */
+    shape?: Shape;
+    /** Frame edge in pixels. Defaults to the shape's `frameSize`. */
+    frameSize?: number;
+    /** Frame budget. Defaults to {@link MAX_FRAMES}. */
+    maxFrames?: number;
+}
+/** Result of rendering one frame. */
+export interface RenderedFrame {
+    /** Base64-encoded PNG, as returned by the native renderer. */
+    data: string;
+    cols: number;
+    rows: number;
+    /** Characters printed (ink toggles excluded; input may be shorter than capacity). */
+    chars: number;
+}
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export interface CompactionPreparation<TMessage = Message> {
+    /** UUID of first entry to keep. */
+    firstKeptEntryId: string;
+    /** Messages that will be archived and discarded. */
+    messagesToSummarize: TMessage[];
+    /** Messages that will be archived as the split-turn prefix, if any. */
+    turnPrefixMessages: TMessage[];
+    tokensBefore: number;
+    /** Summary from previous compaction, for continuity when no prior snapcompact archive exists. */
+    previousSummary?: string;
+    /** Preserved opaque compaction payload from the previous compaction, if any. */
+    previousPreserveData?: Record<string, unknown>;
+    /** File operations extracted by the host agent. */
+    fileOps: FileOperations;
+}
+export interface CompactionResult<T = CompactionDetails> {
+    summary: string;
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    details?: T;
+    preserveData?: Record<string, unknown>;
+}
+export type ConvertToLlm<TMessage = Message> = (messages: TMessage[]) => Message[];
+export declare function createFileOps(): FileOperations;
+export declare function computeFileLists(fileOps: FileOperations): CompactionDetails;
+export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
+/** Default per-tool-result character cap in serialized history. */
+export declare const TOOL_RESULT_MAX_CHARS = 2000;
+/** Default per-argument-value character cap inside serialized tool calls
+ *  (write/edit bodies otherwise dump whole files into the archive). */
+export declare const TOOL_ARG_MAX_CHARS = 500;
+/** Default character cap across one tool call's full serialized argument list. */
+export declare const TOOL_CALL_MAX_CHARS = 2000;
+/** Default fraction of a truncation budget spent on the head; the remainder
+ *  keeps the tail, where command errors and test failures usually land. */
+export declare const TRUNCATE_HEAD_RATIO = 0.6;
+/** Zero-width ink toggles understood by the native renderer (shift-out/in):
+ *  text between them prints in dim gray ink without occupying a cell. */
+export declare const DIM_ON = "\u000E";
+export declare const DIM_OFF = "\u000F";
+/** Character budgets applied while serializing discarded history for frame
+ *  rendering. Pass `Infinity` to disable an individual cap. */
+export interface SerializeOptions {
+    /** Per-tool-result cap. Defaults to {@link TOOL_RESULT_MAX_CHARS}. */
+    toolResultMaxChars?: number;
+    /** Per-argument-value cap. Defaults to {@link TOOL_ARG_MAX_CHARS}. */
+    toolArgMaxChars?: number;
+    /** Whole-argument-list cap per call. Defaults to {@link TOOL_CALL_MAX_CHARS}. */
+    toolCallMaxChars?: number;
+    /** Head share of each budget, clamped to [0, 1]. Defaults to {@link TRUNCATE_HEAD_RATIO}. */
+    truncateHeadRatio?: number;
+    /** Print tool-result text in dim gray ink so archived conversation reads
+     *  louder than archived tool noise. Defaults to `true`. */
+    dimToolResults?: boolean;
+}
+export declare function serializeConversation(messages: Message[], options?: SerializeOptions): string;
+/** Printed in place of newline runs: the native renderer fills this cell
+ *  entirely with pitch-black ink, so line structure survives whitespace
+ *  collapsing at a one-cell cost. */
+export declare const NEWLINE_GLYPH = "\u2588";
+/**
+ * Prepare text for printing: strip ANSI escape sequences, collapse horizontal
+ * whitespace runs to single spaces and newline-bearing runs to one
+ * {@link NEWLINE_GLYPH} (drawn as a pitch-black cell), then fold everything
+ * outside the fonts' ASCII + Latin-1 coverage to ASCII approximations.
+ * Unrenderable control/format/combining characters are dropped without
+ * occupying a cell; `?` remains the fallback for unsupported graphic
+ * characters. The zero-width ink toggles {@link DIM_ON}/{@link DIM_OFF} pass
+ * through untouched.
+ */
+export declare function normalize(text: string): string;
+/**
+ * Wrap each maximal alphabetic run that is a stopword in {@link DIM_ON} /
+ * {@link DIM_OFF} so it prints in dim gray ink. Spans that are already dim
+ * (e.g. archived tool output) pass through untouched — wrapping there would
+ * terminate the enclosing dim span early. Markers are zero-width, so the
+ * visible glyph count is unchanged.
+ */
+export declare function dimStopwords(text: string): string;
+/**
+ * Greedy word-wrap, no mid-word breaks (hard split only for width+ words) —
+ * ported verbatim from `research/exp14_bestgpt.py` `wrap()`. Zero-width dim
+ * markers count toward word length here; serialized history places them at
+ * word boundaries, so the drift is at most one cell per affected line.
+ */
+export declare function wrap(text: string, width: number): string[];
+export declare function geometry(shape: Shape, size?: number): Geometry;
+/** Render one snapcompact frame from already-normalized text. Doc shapes
+ *  (`columns === 2`) expect one page of `\n`-joined pre-wrapped lines. */
+export declare function render(text: string, shape: Shape, size?: number): RenderedFrame;
+/** Options for {@link renderMany} and {@link frames}. */
+export interface RenderManyOptions {
+    /** Explicit shape; wins over `model`. */
+    shape?: Shape;
+    /** Model whose `api` selects the eval-optimal shape. */
+    model?: Pick<Model, "api">;
+    /** Frame edge in px; defaults to the shape's `frameSize`. */
+    frameSize?: number;
+    /** Hard cap on frames produced; omit for unbounded (caller decides usage). */
+    maxFrames?: number;
+}
+/**
+ * Render arbitrary text into snapcompact PNG frames as LLM image blocks
+ * (first page first). Synchronous: safe to call from per-request transforms.
+ * Empty/whitespace-only input yields no frames.
+ */
+export declare function renderMany(text: string, options?: RenderManyOptions): ImageContent[];
+/** Frames needed to hold `text` at the given shape/size, without rendering.
+ *  For doc shapes this wraps the text once and counts pages of `2 * rows`
+ *  lines; for grid shapes it divides by the frame capacity. */
+export declare function frames(text: string, options?: Pick<RenderManyOptions, "shape" | "model" | "frameSize">): number;
+/** Validate and extract a persisted frame archive from `preserveData`. */
+export declare function getPreservedArchive(preserveData: Record<string, unknown> | undefined): Archive | undefined;
+/** Convert archive frames into LLM image blocks (oldest first). */
+export declare function images(archive: Archive): ImageContent[];
+/**
+ * Run a snapcompact compaction over prepared messages. Fully local: serializes
+ * the discarded history, prints it onto PNG frames in the provider-optimal
+ * shape, merges previously archived frames (oldest dropped beyond the
+ * budget), and produces a deterministic summary explaining how to read the
+ * frames. Pages past the frame budget are never rendered (providers with
+ * hard image caps silently drop excess frames on the wire) — the newest
+ * unrendered slice survives verbatim as a text tail on the summary and is
+ * folded back into frames by the next compaction.
+ *
+ * Frames archived under a different shape (provider switches, legacy 5x8
+ * sessions) are kept as-is — each frame carries its own geometry, and the
+ * summary describes the newest shape while noting that older frames may
+ * differ.
+ *
+ * If the previous compaction was text-based, its summary is printed at the
+ * head of the frame archive as `[Summary of earlier history]` so no continuity is lost.
+ */
+export declare function compact<TMessage = Message>(preparation: CompactionPreparation<TMessage>, options?: Options<TMessage>): Promise<CompactionResult>;