@oh-my-pi/snapcompact 15.11.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [Unreleased]
+
+## [15.11.0] - 2026-06-10
+
+### Breaking Changes
+
+- Changed `renderSnapcompactFrame` output from `png: Uint8Array` to `data: string` base64, requiring consumers to read frame payloads from `frame.data`
+
+### Added
+
+- 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 and publication config so consumers can import `@oh-my-pi/snapcompact` with typed access to snapcompact APIs
+- Published `@oh-my-pi/snapcompact` as the reusable snapcompact compaction package, including bitmap-frame rendering helpers, archive helpers, and the local `snapcompactCompact()` strategy.
+
+### Changed
+
+- 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/dist/types/index.d.ts

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

package/dist/types/snapcompact.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Snapcompact compaction: archive conversation history as dense bitmap images.
+ *
+ * Instead of asking an LLM to summarize discarded history, the serialized
+ * conversation is rendered into square PNG frames of pixel-font text that
+ * vision models read back directly, like an archivist at a snapcompact frame
+ * reader.
+ *
+ * The frame shape is provider-aware, following the snapcompact SQuAD evals
+ * (`packages/snapcompact`, 200k-token monolithic runs):
+ *
+ * - **Anthropic** (`8x8r-bw`): unscii-8 square cells, black ink, every line
+ *   printed twice with the copy on a pale highlight band. Read at F1 parity
+ *   with raw text at ~2x lower cost; the colored variants drew refusals at
+ *   scale, the repeated plain shape did not.
+ * - **Google** (`8x8r-sent`): same repeated grid with six-hue sentence
+ *   coloring (0.90 F1 at ~2.9x lower cost on gemini-3.5-flash).
+ * - **OpenAI** (`6x6u-sent`): OpenAI bills a flat ~2.9k tokens per image, so
+ *   image count is the only cost lever — unscii-8 Lanczos-stretched to 6x6
+ *   cells packs the most readable chars per frame. Frames request
+ *   `detail: "original"`; the default `auto` downscale destroys 6px glyphs.
+ * - **Unknown providers** default to the Anthropic shape (most
+ *   refusal-robust). Gateways that resize images (e.g. OpenRouter normalizes
+ *   visual payloads to a fixed token budget) defeat any shape — optical
+ *   context fails silently there.
+ *
+ * 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, Model } from "@oh-my-pi/pi-ai";
+/** One eval-validated frame shape: font, cell, ink, repetition, and size. */
+export interface SnapcompactShape {
+    /** Bundled font in the native renderer. */
+    font: "5x8" | "8x8";
+    /** 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;
+    /** Ink: `sent` cycles six hues at sentence boundaries; `bw` is black. */
+    variant: "sent" | "bw";
+    /** 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"];
+}
+/** Eval-validated shapes, keyed by the provider family they won on. */
+export declare const SNAPCOMPACT_SHAPES: {
+    /** `8x8r-bw`: unscii square, black ink, lines doubled on highlight bands. */
+    readonly anthropic: {
+        readonly font: "8x8";
+        readonly cellWidth: 8;
+        readonly cellHeight: 8;
+        readonly variant: "bw";
+        readonly lineRepeat: 2;
+        readonly frameSize: 1568;
+        readonly frameTokenEstimate: 3300;
+    };
+    /** `8x8r-sent`: the repeated grid with sentence-hue ink. */
+    readonly google: {
+        readonly font: "8x8";
+        readonly cellWidth: 8;
+        readonly cellHeight: 8;
+        readonly variant: "sent";
+        readonly lineRepeat: 2;
+        readonly frameSize: 1568;
+        readonly frameTokenEstimate: 1100;
+    };
+    /** `6x6u-sent`: unscii stretched to 6x6 — densest readable cell, fewest
+     *  frames (OpenAI bills per image, ~2.9k tokens flat). */
+    readonly openaiDense: {
+        readonly font: "8x8";
+        readonly cellWidth: 6;
+        readonly cellHeight: 6;
+        readonly variant: "sent";
+        readonly lineRepeat: 1;
+        readonly frameSize: 1568;
+        readonly frameTokenEstimate: 2900;
+        readonly imageDetail: "original";
+    };
+    /** Original 5x8 X.org shape (pre-shape-table sessions rendered this). */
+    readonly legacy: {
+        readonly font: "5x8";
+        readonly cellWidth: 5;
+        readonly cellHeight: 8;
+        readonly variant: "sent";
+        readonly lineRepeat: 1;
+        readonly frameSize: 2576;
+        readonly frameTokenEstimate: 3300;
+    };
+};
+/** Runtime guard for shape overrides loaded from config or preserve data. */
+export declare function isSnapcompactShape(value: unknown): value is SnapcompactShape;
+/** Pick the eval-optimal frame shape for a provider API. */
+export declare function resolveSnapcompactShape(api?: Api): SnapcompactShape;
+/** Legacy frame edge in pixels (the 5x8 shape's eval-validated size). New
+ *  shapes carry their own `frameSize`. */
+export declare const SNAPCOMPACT_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 SNAPCOMPACT_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 SNAPCOMPACT_FRAME_TOKEN_ESTIMATE = 3300;
+/** Key under `CompactionEntry.preserveData` holding the frame archive. */
+export declare const SNAPCOMPACT_PRESERVE_KEY = "snapcompact";
+/** One developed snapcompact frame: a base64 PNG plus its reading geometry. */
+export interface SnapcompactFrame {
+    /** Base64-encoded PNG. */
+    data: string;
+    mimeType: string;
+    /** Characters per row in the frame grid. */
+    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?: SnapcompactShape["font"];
+    variant?: SnapcompactShape["variant"];
+    lineRepeat?: number;
+    /** Resolution hint forwarded to the provider when re-attaching. */
+    detail?: ImageContent["detail"];
+}
+/** Frame archive persisted under `preserveData[SNAPCOMPACT_PRESERVE_KEY]`. */
+export interface SnapcompactArchive {
+    /** Frames ordered oldest to newest. */
+    frames: SnapcompactFrame[];
+    /** Characters currently readable across all frames. */
+    totalChars: number;
+    /** Characters dropped so far to respect the frame budget. */
+    truncatedChars: number;
+}
+export interface SnapcompactGeometry {
+    cols: number;
+    rows: number;
+    /** Characters that fit one frame (cols * rows). */
+    capacity: number;
+}
+export interface SnapcompactOptions<TMessage = Message> extends SnapcompactSerializeOptions {
+    /** App-level message transformer (same contract as agent-core's `SummaryOptions.convertToLlm`). */
+    convertToLlm?: SnapcompactConvertToLlm<TMessage>;
+    /** Model whose provider API selects the frame shape. */
+    model?: Pick<Model, "api">;
+    /** Explicit shape override; wins over `model`. */
+    shape?: SnapcompactShape;
+    /** Frame edge in pixels. Defaults to the shape's `frameSize`. */
+    frameSize?: number;
+    /** Frame budget. Defaults to {@link SNAPCOMPACT_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 SnapcompactFileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export interface SnapcompactCompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export interface SnapcompactCompactionPreparation<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: SnapcompactFileOperations;
+}
+export interface SnapcompactCompactionResult<T = SnapcompactCompactionDetails> {
+    summary: string;
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    details?: T;
+    preserveData?: Record<string, unknown>;
+}
+export type SnapcompactConvertToLlm<TMessage = Message> = (messages: TMessage[]) => Message[];
+export declare function createSnapcompactFileOps(): SnapcompactFileOperations;
+export declare function computeSnapcompactFileLists(fileOps: SnapcompactFileOperations): SnapcompactCompactionDetails;
+export declare function upsertSnapcompactFileOperations(summary: string, readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
+/** Default per-tool-result character cap in serialized history. */
+export declare const SNAPCOMPACT_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 SNAPCOMPACT_TOOL_ARG_MAX_CHARS = 500;
+/** Default character cap across one tool call's full serialized argument list. */
+export declare const SNAPCOMPACT_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 SNAPCOMPACT_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 SNAPCOMPACT_DIM_ON = "\u000E";
+export declare const SNAPCOMPACT_DIM_OFF = "\u000F";
+/** Character budgets applied while serializing discarded history for frame
+ *  rendering. Pass `Infinity` to disable an individual cap. */
+export interface SnapcompactSerializeOptions {
+    /** Per-tool-result cap. Defaults to {@link SNAPCOMPACT_TOOL_RESULT_MAX_CHARS}. */
+    toolResultMaxChars?: number;
+    /** Per-argument-value cap. Defaults to {@link SNAPCOMPACT_TOOL_ARG_MAX_CHARS}. */
+    toolArgMaxChars?: number;
+    /** Whole-argument-list cap per call. Defaults to {@link SNAPCOMPACT_TOOL_CALL_MAX_CHARS}. */
+    toolCallMaxChars?: number;
+    /** Head share of each budget, clamped to [0, 1]. Defaults to {@link SNAPCOMPACT_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 serializeSnapcompactConversation(messages: Message[], options?: SnapcompactSerializeOptions): string;
+/**
+ * Prepare text for printing: collapse whitespace runs (incl. newlines) to
+ * single spaces — the eval's "paragraph breaks collapsed to spaces" format —
+ * then fold everything outside the fonts' ASCII + Latin-1 coverage to ASCII
+ * approximations (`?` as the last resort).
+ */
+export declare function normalizeForSnapcompact(text: string): string;
+export declare function snapcompactGeometry(shape: SnapcompactShape, size?: number): SnapcompactGeometry;
+/** Render one snapcompact frame from already-normalized text. */
+export declare function renderSnapcompactFrame(text: string, shape: SnapcompactShape, size?: number): RenderedFrame;
+/** Validate and extract a persisted frame archive from `preserveData`. */
+export declare function getPreservedSnapcompactArchive(preserveData: Record<string, unknown> | undefined): SnapcompactArchive | undefined;
+/** Convert archive frames into LLM image blocks (oldest first). */
+export declare function snapcompactImages(archive: SnapcompactArchive): 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.
+ *
+ * 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 snapcompactCompact<TMessage = Message>(preparation: SnapcompactCompactionPreparation<TMessage>, options?: SnapcompactOptions<TMessage>): Promise<SnapcompactCompactionResult>;

package/package.json

@@ -0,0 +1,63 @@
+{
+	"type": "module",
+	"name": "@oh-my-pi/snapcompact",
+	"version": "15.11.0",
+	"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/can1357/oh-my-pi.git",
+		"directory": "packages/snapcompact"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/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/pi-ai": "15.11.0",
+		"@oh-my-pi/pi-natives": "15.11.0",
+		"@oh-my-pi/pi-utils": "15.11.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"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}}

package/src/prompts/snapcompact-summary.md

@@ -0,0 +1,17 @@
+Prior conversation history has been archived verbatim onto {{frameCount}} snapcompact frame{{#if multipleFrames}}s{{/if}} — the bitmap image{{#if multipleFrames}}s{{/if}} attached below{{#if multipleFrames}}, ordered oldest to newest{{/if}}.
+
+Reading a frame: monospace {{fontCell}} pixel font on a white background, {{cols}} characters per row, {{rows}} text rows per frame; read left to right, top to bottom. Text flows continuously with no word wrap, so words may break across row ends. Whitespace runs (including newlines) were collapsed to single spaces. {{#if sentenceInk}}Ink color cycles through six colors, advancing at sentence boundaries — a color change marks a new sentence.{{else}}Glyphs are plain black ink.{{/if}}{{#if dimmedToolResults}} Tool output is printed in dim gray ink — gray text is archived tool output, not conversation.{{/if}}{{#if lineRepeated}} Every text line is printed twice in a row — first on the white background, then repeated on a pale yellow band. The copies are identical: read each line once and use the duplicate only to double-check hard glyphs.{{/if}} Roles are tagged inline as [User]:, [Assistant]:, [Assistant thinking]:, [Assistant tool calls]:, and [Tool result]:.
+{{#if mixedShapes}}
+
+Older frames may use a different font, grid, or ink coloring than described above; the reading order is always the same (left to right, top to bottom, oldest frame first).
+{{/if}}
+{{#if includedPreviousSummary}}
+
+The earliest frame begins with "[Summary of earlier history]" — a condensed digest of context that predates the archived conversation.
+{{/if}}
+{{#if truncatedChars}}
+
+{{truncatedChars}} characters of older history were dropped to respect the frame budget. The first frame (session start) is always kept, so the missing span sits between the first frame and the next.
+{{/if}}
+
+Total archived: {{totalChars}} characters. Consult the frames whenever you need exact earlier details (user wording, decisions, file paths, tool output). If a region is hard to read, re-derive the fact from the workspace (re-read files, re-run commands) rather than guessing.

package/src/snapcompact.ts

@@ -0,0 +1,746 @@
+/**
+ * Snapcompact compaction: archive conversation history as dense bitmap images.
+ *
+ * Instead of asking an LLM to summarize discarded history, the serialized
+ * conversation is rendered into square PNG frames of pixel-font text that
+ * vision models read back directly, like an archivist at a snapcompact frame
+ * reader.
+ *
+ * The frame shape is provider-aware, following the snapcompact SQuAD evals
+ * (`packages/snapcompact`, 200k-token monolithic runs):
+ *
+ * - **Anthropic** (`8x8r-bw`): unscii-8 square cells, black ink, every line
+ *   printed twice with the copy on a pale highlight band. Read at F1 parity
+ *   with raw text at ~2x lower cost; the colored variants drew refusals at
+ *   scale, the repeated plain shape did not.
+ * - **Google** (`8x8r-sent`): same repeated grid with six-hue sentence
+ *   coloring (0.90 F1 at ~2.9x lower cost on gemini-3.5-flash).
+ * - **OpenAI** (`6x6u-sent`): OpenAI bills a flat ~2.9k tokens per image, so
+ *   image count is the only cost lever — unscii-8 Lanczos-stretched to 6x6
+ *   cells packs the most readable chars per frame. Frames request
+ *   `detail: "original"`; the default `auto` downscale destroys 6px glyphs.
+ * - **Unknown providers** default to the Anthropic shape (most
+ *   refusal-robust). Gateways that resize images (e.g. OpenRouter normalizes
+ *   visual payloads to a fixed token budget) defeat any shape — optical
+ *   context fails silently there.
+ *
+ * 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, Model } from "@oh-my-pi/pi-ai";
+import { renderSnapcompactPng } from "@oh-my-pi/pi-natives";
+import { formatGroupedPaths, prompt } from "@oh-my-pi/pi-utils";
+import fileOperationsTemplate from "./prompts/file-operations.md" with { type: "text" };
+import snapcompactSummaryPrompt from "./prompts/snapcompact-summary.md" with { type: "text" };
+
+// ============================================================================
+// Shapes
+// ============================================================================
+
+/** One eval-validated frame shape: font, cell, ink, repetition, and size. */
+export interface SnapcompactShape {
+	/** Bundled font in the native renderer. */
+	font: "5x8" | "8x8";
+	/** 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;
+	/** Ink: `sent` cycles six hues at sentence boundaries; `bw` is black. */
+	variant: "sent" | "bw";
+	/** 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"];
+}
+
+/** Eval-validated shapes, keyed by the provider family they won on. */
+export const SNAPCOMPACT_SHAPES = {
+	/** `8x8r-bw`: unscii square, black ink, lines doubled on highlight bands. */
+	anthropic: {
+		font: "8x8",
+		cellWidth: 8,
+		cellHeight: 8,
+		variant: "bw",
+		lineRepeat: 2,
+		frameSize: 1568,
+		frameTokenEstimate: 3300,
+	},
+	/** `8x8r-sent`: the repeated grid with sentence-hue ink. */
+	google: {
+		font: "8x8",
+		cellWidth: 8,
+		cellHeight: 8,
+		variant: "sent",
+		lineRepeat: 2,
+		frameSize: 1568,
+		frameTokenEstimate: 1100,
+	},
+	/** `6x6u-sent`: unscii stretched to 6x6 — densest readable cell, fewest
+	 *  frames (OpenAI bills per image, ~2.9k tokens flat). */
+	openaiDense: {
+		font: "8x8",
+		cellWidth: 6,
+		cellHeight: 6,
+		variant: "sent",
+		lineRepeat: 1,
+		frameSize: 1568,
+		frameTokenEstimate: 2900,
+		imageDetail: "original",
+	},
+	/** Original 5x8 X.org shape (pre-shape-table sessions rendered this). */
+	legacy: {
+		font: "5x8",
+		cellWidth: 5,
+		cellHeight: 8,
+		variant: "sent",
+		lineRepeat: 1,
+		frameSize: 2576,
+		frameTokenEstimate: 3300,
+	},
+} as const satisfies Record<string, SnapcompactShape>;
+
+/** Runtime guard for shape overrides loaded from config or preserve data. */
+export function isSnapcompactShape(value: unknown): value is SnapcompactShape {
+	if (!value || typeof value !== "object") return false;
+	const shape = value as Record<string, unknown>;
+	const font = shape.font;
+	const variant = shape.variant;
+	const detail = shape.imageDetail;
+	return (
+		(font === "5x8" || font === "8x8") &&
+		typeof shape.cellWidth === "number" &&
+		shape.cellWidth > 0 &&
+		typeof shape.cellHeight === "number" &&
+		shape.cellHeight > 0 &&
+		(variant === "sent" || variant === "bw") &&
+		typeof shape.lineRepeat === "number" &&
+		shape.lineRepeat > 0 &&
+		typeof shape.frameSize === "number" &&
+		shape.frameSize > 0 &&
+		typeof shape.frameTokenEstimate === "number" &&
+		shape.frameTokenEstimate > 0 &&
+		(detail === undefined || detail === "auto" || detail === "low" || detail === "high" || detail === "original")
+	);
+}
+
+/** Pick the eval-optimal frame shape for a provider API. */
+export function resolveSnapcompactShape(api?: Api): SnapcompactShape {
+	switch (api) {
+		case "openai-completions":
+		case "openai-responses":
+		case "openai-codex-responses":
+		case "azure-openai-responses":
+			return SNAPCOMPACT_SHAPES.openaiDense;
+		case "google-generative-ai":
+		case "google-gemini-cli":
+		case "google-vertex":
+			return SNAPCOMPACT_SHAPES.google;
+		default:
+			// anthropic-messages, bedrock-converse-stream, and anything unknown:
+			// the plain repeated grid is the most refusal-robust reader shape.
+			return SNAPCOMPACT_SHAPES.anthropic;
+	}
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Legacy frame edge in pixels (the 5x8 shape's eval-validated size). New
+ *  shapes carry their own `frameSize`. */
+export const SNAPCOMPACT_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 const SNAPCOMPACT_MAX_FRAMES = 8;
+
+/** Conservative per-frame token estimate used for context budgeting
+ *  (upper bound across shapes: Anthropic bills 1568*1568/750 ≈ 3,278). */
+export const SNAPCOMPACT_FRAME_TOKEN_ESTIMATE = 3300;
+
+/** Key under `CompactionEntry.preserveData` holding the frame archive. */
+export const SNAPCOMPACT_PRESERVE_KEY = "snapcompact";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** One developed snapcompact frame: a base64 PNG plus its reading geometry. */
+export interface SnapcompactFrame {
+	/** Base64-encoded PNG. */
+	data: string;
+	mimeType: string;
+	/** Characters per row in the frame grid. */
+	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?: SnapcompactShape["font"];
+	variant?: SnapcompactShape["variant"];
+	lineRepeat?: number;
+	/** Resolution hint forwarded to the provider when re-attaching. */
+	detail?: ImageContent["detail"];
+}
+
+/** Frame archive persisted under `preserveData[SNAPCOMPACT_PRESERVE_KEY]`. */
+export interface SnapcompactArchive {
+	/** Frames ordered oldest to newest. */
+	frames: SnapcompactFrame[];
+	/** Characters currently readable across all frames. */
+	totalChars: number;
+	/** Characters dropped so far to respect the frame budget. */
+	truncatedChars: number;
+}
+
+export interface SnapcompactGeometry {
+	cols: number;
+	rows: number;
+	/** Characters that fit one frame (cols * rows). */
+	capacity: number;
+}
+
+export interface SnapcompactOptions<TMessage = Message> extends SnapcompactSerializeOptions {
+	/** App-level message transformer (same contract as agent-core's `SummaryOptions.convertToLlm`). */
+	convertToLlm?: SnapcompactConvertToLlm<TMessage>;
+	/** Model whose provider API selects the frame shape. */
+	model?: Pick<Model, "api">;
+	/** Explicit shape override; wins over `model`. */
+	shape?: SnapcompactShape;
+	/** Frame edge in pixels. Defaults to the shape's `frameSize`. */
+	frameSize?: number;
+	/** Frame budget. Defaults to {@link SNAPCOMPACT_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;
+}
+
+// ============================================================================
+// Compaction data contracts
+// ============================================================================
+
+export interface SnapcompactFileOperations {
+	read: Set<string>;
+	written: Set<string>;
+	edited: Set<string>;
+}
+
+export interface SnapcompactCompactionDetails {
+	readFiles: string[];
+	modifiedFiles: string[];
+}
+
+export interface SnapcompactCompactionPreparation<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: SnapcompactFileOperations;
+}
+
+export interface SnapcompactCompactionResult<T = SnapcompactCompactionDetails> {
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	details?: T;
+	preserveData?: Record<string, unknown>;
+}
+
+export type SnapcompactConvertToLlm<TMessage = Message> = (messages: TMessage[]) => Message[];
+
+function defaultConvertToLlm<TMessage>(messages: TMessage[]): Message[] {
+	return messages as unknown as Message[];
+}
+
+// ============================================================================
+// File operation helpers
+// ============================================================================
+
+export function createSnapcompactFileOps(): SnapcompactFileOperations {
+	return {
+		read: new Set(),
+		written: new Set(),
+		edited: new Set(),
+	};
+}
+
+export function computeSnapcompactFileLists(fileOps: SnapcompactFileOperations): SnapcompactCompactionDetails {
+	const modified = new Set([...fileOps.edited, ...fileOps.written]);
+	const readFiles = [...fileOps.read].filter(file => !modified.has(file)).sort();
+	const modifiedFiles = [...modified].sort();
+	return { readFiles, modifiedFiles };
+}
+
+/**
+ * Format file operations as one `<files>` tag: a grouped, prefix-folded
+ * directory tree (find-tool shape) with a ` (Read)` / ` (Write)` / ` (RW)`
+ * marker per file. `readSet` is the cumulative read set (`fileOps.read`),
+ * used to tell modified files that were also read (RW) from blind writes.
+ */
+const FILE_OPERATION_SUMMARY_LIMIT = 20;
+
+function stripFileOperationTags(summary: string): string {
+	// Legacy <read-files>/<modified-files> tags are still stripped so summaries
+	// written before the combined <files> tag self-heal on the next compaction.
+	return summary
+		.replace(/<files>[\s\S]*?<\/files>\s*/g, "")
+		.replace(/<read-files>[\s\S]*?<\/read-files>\s*/g, "")
+		.replace(/<modified-files>[\s\S]*?<\/modified-files>\s*/g, "")
+		.trimEnd();
+}
+
+function formatFileOperations(readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string {
+	if (readFiles.length === 0 && modifiedFiles.length === 0) return "";
+	const mode = new Map<string, "Read" | "Write" | "RW">();
+	for (const file of readFiles) mode.set(file, "Read");
+	for (const file of modifiedFiles) mode.set(file, readSet?.has(file) ? "RW" : "Write");
+	const all = [...mode.keys()].sort();
+	let files = formatGroupedPaths(all.slice(0, FILE_OPERATION_SUMMARY_LIMIT), path => ` (${mode.get(path)})`);
+	if (all.length > FILE_OPERATION_SUMMARY_LIMIT) {
+		files += `\n… (${all.length - FILE_OPERATION_SUMMARY_LIMIT} more files omitted)`;
+	}
+	return prompt.render(fileOperationsTemplate, { files });
+}
+
+export function upsertSnapcompactFileOperations(
+	summary: string,
+	readFiles: string[],
+	modifiedFiles: string[],
+	readSet?: ReadonlySet<string>,
+): string {
+	const baseSummary = stripFileOperationTags(summary);
+	const fileOperations = formatFileOperations(readFiles, modifiedFiles, readSet);
+	if (!fileOperations) return baseSummary;
+	if (!baseSummary) return fileOperations;
+	return `${baseSummary}\n\n${fileOperations}`;
+}
+
+// ============================================================================
+// Message serialization
+// ============================================================================
+
+/** Default per-tool-result character cap in serialized history. */
+export const SNAPCOMPACT_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 const SNAPCOMPACT_TOOL_ARG_MAX_CHARS = 500;
+
+/** Default character cap across one tool call's full serialized argument list. */
+export const SNAPCOMPACT_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 const SNAPCOMPACT_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 const SNAPCOMPACT_DIM_ON = "\u000e";
+export const SNAPCOMPACT_DIM_OFF = "\u000f";
+
+/** Character budgets applied while serializing discarded history for frame
+ *  rendering. Pass `Infinity` to disable an individual cap. */
+export interface SnapcompactSerializeOptions {
+	/** Per-tool-result cap. Defaults to {@link SNAPCOMPACT_TOOL_RESULT_MAX_CHARS}. */
+	toolResultMaxChars?: number;
+	/** Per-argument-value cap. Defaults to {@link SNAPCOMPACT_TOOL_ARG_MAX_CHARS}. */
+	toolArgMaxChars?: number;
+	/** Whole-argument-list cap per call. Defaults to {@link SNAPCOMPACT_TOOL_CALL_MAX_CHARS}. */
+	toolCallMaxChars?: number;
+	/** Head share of each budget, clamped to [0, 1]. Defaults to {@link SNAPCOMPACT_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;
+}
+
+/** Keep the head and tail of `text`, eliding the middle beyond `maxChars`. */
+function truncateForSummary(text: string, maxChars: number, headRatio: number): string {
+	if (text.length <= maxChars) return text;
+	const ratio = Math.min(Math.max(headRatio, 0), 1);
+	const headChars = Math.round(maxChars * ratio);
+	const tailChars = maxChars - headChars;
+	const elided = text.length - maxChars;
+	const tail = tailChars > 0 ? text.slice(-tailChars) : "";
+	return `${text.slice(0, headChars)} [... ${elided} chars elided ...] ${tail}`;
+}
+
+const DIM_MARKERS = /[\u000e\u000f]/g;
+
+/** Strip stray ink toggles from raw content so it cannot forge dim spans. */
+function stripDimMarkers(text: string): string {
+	return text.replace(DIM_MARKERS, "");
+}
+
+export function serializeSnapcompactConversation(messages: Message[], options?: SnapcompactSerializeOptions): string {
+	const toolResultMaxChars = options?.toolResultMaxChars ?? SNAPCOMPACT_TOOL_RESULT_MAX_CHARS;
+	const toolArgMaxChars = options?.toolArgMaxChars ?? SNAPCOMPACT_TOOL_ARG_MAX_CHARS;
+	const toolCallMaxChars = options?.toolCallMaxChars ?? SNAPCOMPACT_TOOL_CALL_MAX_CHARS;
+	const headRatio = options?.truncateHeadRatio ?? SNAPCOMPACT_TRUNCATE_HEAD_RATIO;
+	const dimToolResults = options?.dimToolResults !== false;
+	const parts: string[] = [];
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			const content =
+				typeof msg.content === "string"
+					? msg.content
+					: msg.content
+							.filter((content): content is { type: "text"; text: string } => content.type === "text")
+							.map(content => content.text)
+							.join("");
+			if (content) parts.push(`[User]: ${stripDimMarkers(content)}`);
+		} else if (msg.role === "assistant") {
+			const textParts: string[] = [];
+			const thinkingParts: string[] = [];
+			const toolCalls: string[] = [];
+
+			for (const block of msg.content) {
+				if (block.type === "text") {
+					textParts.push(stripDimMarkers(block.text));
+				} else if (block.type === "thinking") {
+					thinkingParts.push(stripDimMarkers(block.thinking));
+				} else if (block.type === "toolCall") {
+					const args = block.arguments as Record<string, unknown>;
+					const argsStr = truncateForSummary(
+						Object.entries(args)
+							.map(
+								([key, value]) =>
+									`${key}=${truncateForSummary(JSON.stringify(value) ?? "undefined", toolArgMaxChars, headRatio)}`,
+							)
+							.join(", "),
+						toolCallMaxChars,
+						headRatio,
+					);
+					toolCalls.push(`${block.name}(${argsStr})`);
+				}
+			}
+
+			if (thinkingParts.length > 0) {
+				parts.push(`[Assistant thinking]: ${thinkingParts.join("\n")}`);
+			}
+			if (textParts.length > 0) {
+				parts.push(`[Assistant]: ${textParts.join("\n")}`);
+			}
+			if (toolCalls.length > 0) {
+				parts.push(`[Assistant tool calls]: ${toolCalls.join("; ")}`);
+			}
+		} else if (msg.role === "toolResult") {
+			const content = msg.content
+				.filter((block): block is { type: "text"; text: string } => block.type === "text")
+				.map(block => block.text)
+				.join("");
+			if (content) {
+				// Args above are JSON-escaped, so only raw result text can carry toggles.
+				const body = truncateForSummary(stripDimMarkers(content), toolResultMaxChars, headRatio);
+				parts.push(
+					dimToolResults
+						? `[Tool result]: ${SNAPCOMPACT_DIM_ON}${body}${SNAPCOMPACT_DIM_OFF}`
+						: `[Tool result]: ${body}`,
+				);
+			}
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+// ============================================================================
+// Preserve-data helpers
+// ============================================================================
+
+const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+
+function stripOpenAiRemoteCompactionPreserveData(
+	preserveData: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+	if (!preserveData || !(OPENAI_REMOTE_COMPACTION_PRESERVE_KEY in preserveData)) {
+		return preserveData;
+	}
+	const { [OPENAI_REMOTE_COMPACTION_PRESERVE_KEY]: _removed, ...rest } = preserveData;
+	return Object.keys(rest).length > 0 ? rest : undefined;
+}
+
+// ============================================================================
+// Text normalization
+// ============================================================================
+
+/** Folds for common non-Latin-1 characters the bundled fonts cannot draw. */
+const CHAR_FOLD: Record<string, string> = {
+	"\u2018": "'",
+	"\u2019": "'",
+	"\u201a": "'",
+	"\u201b": "'",
+	"\u201c": '"',
+	"\u201d": '"',
+	"\u201e": '"',
+	"\u2013": "-",
+	"\u2014": "-",
+	"\u2015": "-",
+	"\u2212": "-",
+	"\u2026": "...",
+	"\u2022": "*",
+	"\u25cf": "*",
+	"\u25a0": "*",
+	"\u25aa": "*",
+	"\u2190": "<-",
+	"\u2192": "->",
+	"\u21d2": "=>",
+	"\u2713": "v",
+	"\u2714": "v",
+	"\u2717": "x",
+	"\u2718": "x",
+};
+
+/**
+ * Prepare text for printing: collapse whitespace runs (incl. newlines) to
+ * single spaces — the eval's "paragraph breaks collapsed to spaces" format —
+ * then fold everything outside the fonts' ASCII + Latin-1 coverage to ASCII
+ * approximations (`?` as the last resort).
+ */
+export function normalizeForSnapcompact(text: string): string {
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	let out = "";
+	for (const ch of collapsed) {
+		const cp = ch.codePointAt(0) as number;
+		if (cp < 0x7f || (cp >= 0xa0 && cp <= 0xff)) {
+			out += ch;
+			continue;
+		}
+		const fold = CHAR_FOLD[ch];
+		if (fold !== undefined) {
+			out += fold;
+		} else if (cp >= 0x2500 && cp <= 0x257f) {
+			// Box drawing: keep table skeletons legible.
+			out += cp === 0x2502 || cp === 0x2503 ? "|" : cp === 0x2500 || cp === 0x2501 ? "-" : "+";
+		} else {
+			out += "?";
+		}
+	}
+	return out;
+}
+
+// ============================================================================
+// Rendering
+// ============================================================================
+
+export function snapcompactGeometry(shape: SnapcompactShape, size: number = shape.frameSize): SnapcompactGeometry {
+	const cols = Math.floor(size / shape.cellWidth);
+	const rows = Math.floor(size / shape.cellHeight / shape.lineRepeat);
+	return { cols, rows, capacity: cols * rows };
+}
+
+/** Render one snapcompact frame from already-normalized text. */
+export function renderSnapcompactFrame(
+	text: string,
+	shape: SnapcompactShape,
+	size: number = shape.frameSize,
+): RenderedFrame {
+	const { cols, rows, capacity } = snapcompactGeometry(shape, size);
+	const visible = text.length - (text.match(DIM_MARKERS)?.length ?? 0);
+	const chars = Math.min(visible, capacity);
+	const data = renderSnapcompactPng(text, {
+		size,
+		font: shape.font,
+		cellWidth: shape.cellWidth,
+		cellHeight: shape.cellHeight,
+		variant: shape.variant,
+		lineRepeat: shape.lineRepeat,
+	});
+	return { data, cols, rows, chars };
+}
+
+// ============================================================================
+// Archive helpers
+// ============================================================================
+
+/** Validate and extract a persisted frame archive from `preserveData`. */
+export function getPreservedSnapcompactArchive(
+	preserveData: Record<string, unknown> | undefined,
+): SnapcompactArchive | undefined {
+	const candidate = preserveData?.[SNAPCOMPACT_PRESERVE_KEY];
+	if (!candidate || typeof candidate !== "object") return undefined;
+	const archive = candidate as SnapcompactArchive;
+	if (!Array.isArray(archive.frames)) return undefined;
+	const frames = archive.frames.filter(
+		frame =>
+			!!frame &&
+			typeof frame.data === "string" &&
+			frame.data.length > 0 &&
+			typeof frame.mimeType === "string" &&
+			typeof frame.cols === "number" &&
+			typeof frame.rows === "number" &&
+			typeof frame.chars === "number",
+	);
+	if (frames.length === 0) return undefined;
+	return {
+		frames,
+		totalChars: typeof archive.totalChars === "number" ? archive.totalChars : 0,
+		truncatedChars: typeof archive.truncatedChars === "number" ? archive.truncatedChars : 0,
+	};
+}
+
+/** Convert archive frames into LLM image blocks (oldest first). */
+export function snapcompactImages(archive: SnapcompactArchive): ImageContent[] {
+	return archive.frames.map(frame => ({
+		type: "image",
+		data: frame.data,
+		mimeType: frame.mimeType,
+		...(frame.detail ? { detail: frame.detail } : {}),
+	}));
+}
+
+// ============================================================================
+// Compaction entry point
+// ============================================================================
+
+/**
+ * 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.
+ *
+ * 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 async function snapcompactCompact<TMessage = Message>(
+	preparation: SnapcompactCompactionPreparation<TMessage>,
+	options?: SnapcompactOptions<TMessage>,
+): Promise<SnapcompactCompactionResult> {
+	const { firstKeptEntryId, tokensBefore, previousSummary, previousPreserveData, fileOps } = preparation;
+	if (!firstKeptEntryId) {
+		throw new Error("First kept entry has no ID - session may need migration");
+	}
+	const shape = options?.shape ?? resolveSnapcompactShape(options?.model?.api);
+	const frameSize = options?.frameSize ?? shape.frameSize;
+	const maxFrames = Math.max(1, options?.maxFrames ?? SNAPCOMPACT_MAX_FRAMES);
+	const geometry = snapcompactGeometry(shape, frameSize);
+
+	const messages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
+	const llmMessages = (options?.convertToLlm ?? defaultConvertToLlm)(messages);
+	let archiveText = normalizeForSnapcompact(serializeSnapcompactConversation(llmMessages, options));
+
+	const previousArchive = getPreservedSnapcompactArchive(previousPreserveData);
+	const includedPreviousSummary = !previousArchive && !!previousSummary;
+	if (includedPreviousSummary && previousSummary) {
+		const head = `[Summary of earlier history] ${normalizeForSnapcompact(previousSummary)}`;
+		archiveText = archiveText.length > 0 ? `${head} [Recent conversation] ${archiveText}` : head;
+	}
+
+	let truncatedChars = previousArchive?.truncatedChars ?? 0;
+
+	const newFrames: SnapcompactFrame[] = [];
+	let dimOpen = false;
+	for (let offset = 0; offset < archiveText.length; offset += geometry.capacity) {
+		let chunk = archiveText.slice(offset, offset + geometry.capacity);
+		// Re-open a dim span that the previous frame boundary cut through.
+		if (dimOpen) chunk = SNAPCOMPACT_DIM_ON + chunk;
+		dimOpen = chunk.lastIndexOf(SNAPCOMPACT_DIM_ON) > chunk.lastIndexOf(SNAPCOMPACT_DIM_OFF);
+		const rendered = renderSnapcompactFrame(chunk, shape, frameSize);
+		newFrames.push({
+			data: rendered.data,
+			mimeType: "image/png",
+			cols: rendered.cols,
+			rows: rendered.rows,
+			chars: rendered.chars,
+			font: shape.font,
+			variant: shape.variant,
+			lineRepeat: shape.lineRepeat,
+			...(shape.imageDetail ? { detail: shape.imageDetail } : {}),
+		});
+		// Keep the event loop responsive between native render passes.
+		await Bun.sleep(0);
+	}
+
+	const frames = [...(previousArchive?.frames ?? []), ...newFrames];
+	if (frames.length > maxFrames) {
+		// Pin the earliest frame: it anchors the session head (the original
+		// request, or the filmed summary of even older history) the way the
+		// LLM-summary strategies keep the original goal alive across rounds.
+		// Eviction removes the oldest *unpinned* frames, so the archive fades
+		// from the middle out — head and tail survive. With a budget of one
+		// frame the pin is moot; keep the newest frame instead.
+		const evictStart = maxFrames >= 2 ? 1 : 0;
+		const dropped = frames.splice(evictStart, frames.length - maxFrames);
+		for (const frame of dropped) truncatedChars += frame.chars;
+	}
+	const totalChars = frames.reduce((sum, frame) => sum + frame.chars, 0);
+	const mixedShapes = frames.some(
+		frame =>
+			frame.cols !== geometry.cols ||
+			frame.rows !== geometry.rows ||
+			(frame.variant ?? "sent") !== shape.variant ||
+			(frame.lineRepeat ?? 1) !== shape.lineRepeat,
+	);
+
+	let summary: string;
+	if (frames.length === 0) {
+		summary = "No prior history.";
+	} else {
+		summary = prompt.render(snapcompactSummaryPrompt, {
+			frameCount: frames.length,
+			multipleFrames: frames.length > 1,
+			fontCell: `${shape.cellWidth}x${shape.cellHeight}`,
+			cols: geometry.cols,
+			rows: geometry.rows,
+			sentenceInk: shape.variant === "sent",
+			lineRepeated: shape.lineRepeat > 1,
+			dimmedToolResults: options?.dimToolResults !== false,
+			mixedShapes,
+			totalChars,
+			truncatedChars,
+			includedPreviousSummary,
+		});
+	}
+	const { readFiles, modifiedFiles } = computeSnapcompactFileLists(fileOps);
+	summary = upsertSnapcompactFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
+
+	// A snapcompact pass replaces any provider-side replacement history; strip the
+	// OpenAI remote-compaction payload like the default summarizer path does.
+	const basePreserve = stripOpenAiRemoteCompactionPreserveData(previousPreserveData) ?? {};
+	const archive: SnapcompactArchive = { frames, totalChars, truncatedChars };
+
+	return {
+		summary,
+		shortSummary: `Archived ${totalChars.toLocaleString()} chars of history onto ${frames.length} snapcompact frame${frames.length === 1 ? "" : "s"}`,
+		firstKeptEntryId,
+		tokensBefore,
+		details: { readFiles, modifiedFiles },
+		preserveData: { ...basePreserve, [SNAPCOMPACT_PRESERVE_KEY]: archive },
+	};
+}