@oh-my-pi-zen/snapcompact 16.3.6-zen.1

package/dist/types/snapcompact.d.ts

@@ -0,0 +1,586 @@
+/**
+ * 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. `providerImageBudget`
+ *   still caps per-request images per provider so inline imaging cannot flood a
+ *   request with attachments, but the old OpenRouter-specific 8-image cap is
+ *   gone; routers now use the same permissive budget as direct Anthropic/Claude
+ *   lines unless configured otherwise upstream.
+ *
+ * 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/pi-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, TextContent } from "@oh-my-pi-zen/pi-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" | "silver";
+    /** 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),
+ * `silver16` the embedded Silver TrueType font on a 16px grid for CJK and
+ * other non-Latin text, and `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 "silver16-bw": {
+        readonly font: "silver";
+        readonly cellWidth: 16;
+        readonly cellHeight: 16;
+        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 pi-ai
+ * `Model` or any `{ api, id }` subset.
+ */
+export declare function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape;
+/**
+ * Pick the frame shape for `text` without changing the selected shape.
+ *
+ * Glyph-level Silver fallback happens during normalization/rendering, so this
+ * helper exists for callers that need a text-aware API name while preserving
+ * explicit and provider-selected shapes.
+ */
+export declare function resolveShapeForText(_text: string, 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;
+/** Default upper bound on archive frames carried per compaction. Sized to hold
+ *  ~400k tokens of the high-res Anthropic frame Opus reads (1932px ≈ 5,000
+ *  billed tokens each → 80 frames) while staying under the ~100-image
+ *  per-request wire cap. Oldest frames are dropped first once the budget is
+ *  exceeded (mirrors how iterative text summaries fade the oldest detail); a
+ *  caller may pass a lower `maxFrames` upper limit, and per-model context
+ *  fitting is handled by the caller's overflow guard. */
+export declare const MAX_FRAMES_DEFAULT = 80;
+/** High-quality (legible) frames rendered at each chronological edge of a
+ *  foveated archive — the session head (oldest) and the slice just before the
+ *  text region (newest) — with the denser low-quality tier filling the middle. */
+export declare const HQ_EDGE_FRAMES = 3;
+/** Conservative per-frame token estimate used for context budgeting — the
+ *  upper bound across shapes: high-res Claude frames hit the 4,784 visual-token
+ *  cap, billed at +5% margin (ceil(4784 * 1.05)). Keeps the overflow guard from
+ *  undercounting a high-res archive at the raised {@link MAX_FRAMES_DEFAULT}. */
+export declare const FRAME_TOKEN_ESTIMATE = 5024;
+/** Conservative upper bound for one persisted frame's base64 payload. The
+ *  measured high-res Anthropic `8x13`/`11on16` PNG frames sit around 159 KB;
+ *  170 KB leaves margin for denser glyph pages without permitting multi-MB
+ *  standing request bodies at large context windows. */
+export declare const FRAME_DATA_BYTES_ESTIMATE = 170000;
+/** Maximum snapcompact image base64 carried in every rebuilt provider request.
+ *  Above this, provider backends can accept the HTTP body but fail mid-stream
+ *  with opaque 5xx errors. Keep this independent from visual-token budgeting:
+ *  a 1M-token model can afford 70 images on paper, but not the resulting
+ *  ~11 MB JSON payload on every turn. */
+export declare const FRAME_DATA_BYTES_BUDGET = 3000000;
+/** Frame-count cap implied by {@link FRAME_DATA_BYTES_BUDGET}. */
+export declare function maxFramesForDataBudget(maxFrameDataBytes?: number): number;
+/** Base64 byte length for persisted snapcompact frames. */
+export declare function frameDataBytes(frames: readonly Pick<Frame, "data">[]): number;
+/**
+ * Per-request image-count budgets by provider id. These cap how many images an
+ * entire request may carry (archive/system-prompt/tool-result imaging combined).
+ * The values are conservative policy caps under the vendor hard limits
+ * (Anthropic 100, OpenAI 500, Gemini ~2500); unknown providers fall to a safe
+ * floor rather than sending unbounded attachments.
+ */
+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;
+/** 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 {
+    /** Rendered frames ordered oldest to newest, re-derived from {@link text}
+     *  each compaction with foveated quality tiers (HQ/LQ/HQ inside the imaged
+     *  middle). May be empty when the whole archive fits in text. */
+    frames: Frame[];
+    /** Characters currently readable across all frames plus the text regions. */
+    totalChars: number;
+    /** Characters dropped so far to respect the archive budget. */
+    truncatedChars: number;
+    /** Full kept archive source (oldest to newest, normalized, bounded to the
+     *  rendered budget) — the single source re-rendered each compaction. */
+    text?: string;
+    /** Oldest text region kept verbatim around the imaged middle. */
+    textHead?: string;
+    /** Newest text region kept verbatim around the imaged middle. */
+    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 and id select the frame shape. */
+    model?: ShapeTarget;
+    /** Explicit shape override; wins over `model`. */
+    shape?: Shape;
+    /** Frame edge in pixels. Defaults to the shape's `frameSize`. */
+    frameSize?: number;
+    /** Upper limit on archive frames; clamped to (and defaulting to) {@link MAX_FRAMES_DEFAULT}. */
+    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 isUrlSchemePath(path: string): boolean;
+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";
+export interface NormalizeOptions {
+    /** Shape whose font is tried before the embedded Silver fallback. */
+    shape?: Pick<Shape, "font">;
+    /** Native font name when a full shape is not available. */
+    font?: Shape["font"];
+}
+/**
+ * Prepare text for printing: strip ANSI escape sequences, collapse horizontal
+ * whitespace runs, fold unsupported symbols (including box drawing to ASCII),
+ * preserve Unicode glyphs that either the selected font or embedded Silver
+ * fallback can render, and drop decorative emoji instead of printing `?`.
+ */
+export declare function normalize(text: string, options?: NormalizeOptions): string;
+/**
+ * Scan text with the same font-aware path as {@link normalize}; unsafe means
+ * more than 5% of graphic characters would hit the `?` fallback.
+ */
+export declare function scanRenderability(text: string, options?: NormalizeOptions): {
+    isSafe: boolean;
+    unrenderableRatio: number;
+};
+/**
+ * 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, wideCells?: boolean): 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): Promise<RenderedFrame>;
+/** Options for {@link renderMany} and {@link frames}. */
+export interface RenderManyOptions {
+    /** Explicit shape; wins over `model`. */
+    shape?: Shape;
+    /** Model whose provider API and id select the frame shape. */
+    model?: ShapeTarget;
+    /** 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). Empty/whitespace-only input yields no frames.
+ */
+export declare function renderMany(text: string, options?: RenderManyOptions): Promise<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;
+/** Drop the persisted frame archive ({@link PRESERVE_KEY}) from `preserveData`,
+ *  returning the remaining state — or `undefined` when nothing else remains, so
+ *  an empty `{}` is never persisted. Callers strip the archive once its frames
+ *  have been migrated into a new compaction's text, preventing the stale frames
+ *  from leaking back into the rebuilt context. */
+export declare function stripPreservedArchive(preserveData: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/** Extract persisted archive source text as plain text for LLM summarization. */
+export declare function archiveSourceText(archive: Archive): string | undefined;
+/** Build the text used to choose and preflight a font-aware snapcompact shape. */
+export declare function renderabilityProbeText(serialized: string, previousPreserveData?: Record<string, unknown>, previousSummary?: string): string;
+/** Options for reconstructing a persisted snapcompact archive into prompt blocks. */
+export interface HistoryBlockOptions {
+    /** Hard cap on image base64 bytes attached to one rebuilt provider request. */
+    maxFrameDataBytes?: number;
+}
+/** Convert archive frames into LLM image blocks (oldest first). */
+export declare function images(archive: Archive): ImageContent[];
+/** Ordered archive blocks for a compaction summary message, oldest to newest:
+ *  the oldest text region, the imaged middle, then the newest text region.
+ *  Runtime-only; reconstructed from {@link Archive} on each context rebuild
+ *  instead of persisted on the session entry. */
+export declare function historyBlocks(archive: Archive, options?: HistoryBlockOptions): (TextContent | ImageContent)[];
+/**
+ * Run a snapcompact compaction over prepared messages. Fully local: serializes
+ * the discarded history, appends it to the accumulated archive source text, and
+ * re-renders that source into an ordered history layout: plain text at the
+ * oldest edge, imaged middle, then plain text at the newest edge. The imaged
+ * middle itself foveates (HQ/LQ/HQ) when it grows large.
+ *
+ * The full kept source persists on the archive (`text`) so each later compaction
+ * unfolds and re-renders it coherently alongside the newly archived history.
+ *
+ * If the previous compaction was text-based, its summary is printed at the head
+ * of the 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>;

package/package.json

@@ -0,0 +1,65 @@
+{
+	"type": "module",
+	"name": "@oh-my-pi-zen/snapcompact",
+	"version": "16.3.6-zen.1",
+	"description": "Bitmap-frame context compression for vision-capable LLMs",
+	"homepage": "https://omp.sh",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cagedbird043/oh-my-pi-zen.git",
+		"directory": "packages/snapcompact"
+	},
+	"bugs": {
+		"url": "https://github.com/cagedbird043/oh-my-pi-zen/issues"
+	},
+	"keywords": [
+		"context-compression",
+		"vision",
+		"compaction",
+		"llm"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@oh-my-pi-zen/pi-ai": "16.3.6-zen.1",
+		"@oh-my-pi-zen/pi-natives": "16.3.6-zen.1",
+		"@oh-my-pi-zen/pi-utils": "16.3.6-zen.1",
+		"@oh-my-pi-zen/pi-wire": "16.3.6-zen.1"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./snapcompact": {
+			"types": "./dist/types/snapcompact.d.ts",
+			"import": "./src/snapcompact.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		}
+	}
+}

package/src/index.ts

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

package/src/prompts/file-operations.md

@@ -0,0 +1,5 @@
+{{#if files}}
+{{#xml "files"}}
+{{files}}
+{{/xml}}
+{{/if}}