@oh-my-pi/snapcompact 16.0.11 → 16.1.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [16.1.0] - 2026-06-19
+
+### Added
+
+- Added `historyBlocks(archive)` to reconstruct ordered history blocks from archive data
+
+### Changed
+
+- Refactored compaction to be text-sourced, re-rendering from unified `Archive.text` source
+- Implemented foveated archive layout (HQ edges, dense LQ middle) for optimized context usage
+- Raised `MAX_FRAMES_DEFAULT` to 80 and consolidated `PROVIDER_IMAGE_BUDGETS`
+- Updated OpenRouter to use standard 90-image budget
+- Updated prompt instructions to clearly distinguish between plain-text and image history regions
+- `Options.maxFrames` is now an upper limit clamped to `MAX_FRAMES_DEFAULT`, not a per-call default
+- Rewrote the resume summary prompt into a structured reading guide (turn headings, grid/two-column layout, ink notes) and render file operations inline as a `FILES` section instead of a spliced `<files>` tag
+
+### Fixed
+
+- Fixed context budget undercounting by raising `FRAME_TOKEN_ESTIMATE` to 5024
+- Improved file list formatting in compaction summaries
+
 ## [16.0.11] - 2026-06-19
 
 ### Changed

package/README.md

@@ -49,18 +49,18 @@ Run a full compaction pass over prepared messages:
 ```ts
 import { compact } from "@oh-my-pi/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()
+const result = await compact(preparation, { model });
+// result.summary        — short "resume prior conversation" lead-in, reading guide, and FILES section
+// result.preserveData   — bounded archive source + rendered image middle
 ```
 
 ## API surface
 
-- **Compaction**: `compact`, `CompactionPreparation`, `CompactionResult`, `getPreservedArchive`, `images`
+- **Compaction**: `compact`, `CompactionPreparation`, `CompactionResult`, `getPreservedArchive`, `images`, `historyBlocks`
 - **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`
+- **Budgets**: `providerImageBudget`, `MAX_FRAMES_DEFAULT`, `FRAME_TOKEN_ESTIMATE`, `HQ_EDGE_FRAMES`
 - **File ops**: `createFileOps`, `computeFileLists`, `upsertFileOperations`
 
 ## References

package/dist/types/snapcompact.d.ts

@@ -31,14 +31,11 @@
  *   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.
+ * - **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
@@ -46,7 +43,7 @@
  * 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 type { Api, ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
 /** One eval-validated frame shape: font, cell, ink, repetition, and size. */
 export interface Shape {
     /** Bundled font in the native renderer. */
@@ -286,28 +283,35 @@ export declare function resolveShape(model?: ShapeTarget, variant?: ShapeVariant
 /** 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;
+/** 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;
 /**
- * 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).
+ * 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;
-/** 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. */
@@ -334,16 +338,20 @@ export interface Frame {
 }
 /** Frame archive persisted under `preserveData[PRESERVE_KEY]`. */
 export interface Archive {
-    /** Frames ordered oldest to newest. */
+    /** 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. */
+    /** Characters currently readable across all frames plus the text regions. */
     totalChars: number;
-    /** Characters dropped so far to respect the frame budget. */
+    /** Characters dropped so far to respect the archive 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. */
+    /** 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 {
@@ -363,7 +371,7 @@ export interface Options<TMessage = Message> extends SerializeOptions {
     shape?: Shape;
     /** Frame edge in pixels. Defaults to the shape's `frameSize`. */
     frameSize?: number;
-    /** Frame budget. Defaults to {@link MAX_FRAMES}. */
+    /** Upper limit on archive frames; clamped to (and defaulting to) {@link MAX_FRAMES_DEFAULT}. */
     maxFrames?: number;
 }
 /** Result of rendering one frame. */
@@ -504,22 +512,22 @@ export declare function frames(text: string, options?: Pick<RenderManyOptions, "
 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[];
+/** 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): (TextContent | 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.
+ * 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.
  *
- * 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.
+ * 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 frame archive as `[Summary of earlier history]` so no continuity is lost.
+ * 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

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/snapcompact",
-	"version": "16.0.11",
+	"version": "16.1.0",
 	"description": "Bitmap-frame context compression for vision-capable LLMs",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,10 +31,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "16.0.11",
-		"@oh-my-pi/pi-natives": "16.0.11",
-		"@oh-my-pi/pi-utils": "16.0.11",
-		"@oh-my-pi/pi-wire": "16.0.11"
+		"@oh-my-pi/pi-ai": "16.1.0",
+		"@oh-my-pi/pi-natives": "16.1.0",
+		"@oh-my-pi/pi-utils": "16.1.0",
+		"@oh-my-pi/pi-wire": "16.1.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/prompts/snapcompact-summary.md

@@ -1,32 +1,24 @@
-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}}.
+You are resuming a prior conversation. Its earlier turns were archived to reclaim context and are reproduced under HISTORY below, oldest to newest. Read HISTORY in full, then continue from the live conversation that follows it.
 
-Reading a frame: a solid black cell marks a newline and runs of spaces collapse to one; each turn opens with a heading — # User ¶, # Assistant ¶, or # Tool call ¶ — with assistant reasoning in _italics_ and tool output inside <out>…</out>.
-{{#if docColumns}}- Two side-by-side text columns, each {{cols}} characters wide and up to {{rows}} rows tall: read the left column top to bottom, then the right.
-{{else}}- A single grid {{cols}} characters wide and up to {{rows}} rows tall: read left to right, top to bottom — no word wrap, so words may break across rows.
-{{/if}}
-{{#if sentenceInk}}- Ink cycles six colors, one per sentence.
-{{/if}}{{#if stopwordDimmed}}- Function words are dim gray; content words keep full ink.
-{{/if}}{{#if dimmedToolResults}}- Text inside <out> is dim gray; that gray is archived tool output, not conversation.
-{{/if}}{{#if lineRepeated}}- Each line is printed twice (white, then a pale-yellow band); the copies are identical.
-{{/if}}
-{{#if mixedShapes}}
+The archived transcript is compact: each turn opens with a heading — `# User ¶`, `# Assistant ¶`, or `# Tool call ¶` — assistant reasoning is wrapped in _italics_, and tool output sits inside `<out>…</out>`.
 
-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}}
+Reading HISTORY:
+- Plain-text sections are the verbatim transcript — rely on them exactly.
+{{#if frameCount}}- Some middle sections are attached as images instead of text. Each image is a page of that same transcript and belongs at its place in the reading order, between marked delimiters. Within an image, a solid black cell marks a newline and runs of spaces collapse to one.
+{{#if docColumns}}  - A frame holds two side-by-side columns, each {{cols}} characters wide and up to {{rows}} rows tall: read the left column top to bottom, then the right.
+{{else}}  - A frame is one grid {{cols}} characters wide and up to {{rows}} rows tall: read left to right, top to bottom — there is no word wrap, so a word may break across rows.
+{{/if}}{{#if sentenceInk}}  - Ink cycles through six colors, one per sentence.
+{{/if}}{{#if stopwordDimmed}}  - Function words are dim gray; content words keep full ink.
+{{/if}}{{#if dimmedToolResults}}  - Text inside `<out>` is dim gray — that gray is archived tool output, not conversation.
+{{/if}}{{#if lineRepeated}}  - Each line is printed twice (white, then a pale-yellow band); the two copies are identical.
+{{/if}}{{#if mixedShapes}}  - The compressed middle frames use a smaller, denser font than the edge frames; the reading order is unchanged.
+{{/if}}{{/if}}{{#if includedPreviousSummary}}- HISTORY opens with a condensed digest of still-older context that predates the archived turns.
+{{/if}}{{#if truncatedChars}}- About {{truncatedChars}} characters of older middle history were dropped to fit the archive budget.
+{{/if}}- When an exact earlier detail matters and a section reads unclearly, re-derive it from the workspace (re-read files, re-run commands) rather than guessing.
 
-The earliest frame begins with "[Summary of earlier history]" — a condensed digest of context that predates the archived conversation.
-{{/if}}
-{{#if truncatedChars}}
+{{#if files}}FILES
+===================
+{{files}}
 
-{{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.
-{{#if textTail}}
-
-The frame budget ran out before the newest part of the archive. That remainder continues below as plain text — it is newer than every frame and ends where the live conversation resumes.
-
-[Archived history, continued as text]
-{{textTail}}
-{{/if}}
+{{/if}}HISTORY
+===================

package/src/snapcompact.ts

@@ -31,14 +31,11 @@
  *   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.
+ * - **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
@@ -47,7 +44,7 @@
  * re-attached to the compaction summary message on every context rebuild.
  */
 
-import type { Api, ImageContent, Message, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
 import { renderSnapcompactPng } from "@oh-my-pi/pi-natives";
 import { formatGroupedPaths, prompt } from "@oh-my-pi/pi-utils";
 import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
@@ -301,6 +298,16 @@ const FAMILY_VARIANT: Record<BillingFamily, ShapeVariantName> = {
 	openai: "8on22-bw",
 };
 
+/** Denser companion variant per family for the foveated archive middle: same
+ *  pixels (identical per-frame bill) but a tighter 8px cell, trading some
+ *  legibility for ~40% more chars per frame so the least-important middle of a
+ *  long archive compresses into fewer frames. */
+const FAMILY_VARIANT_LOW: Record<BillingFamily, ShapeVariantName> = {
+	anthropic: "8on16-bw",
+	google: "8on16-bw",
+	openai: "8on16-bw",
+};
+
 const FAMILY_SHAPE: Record<BillingFamily, Shape> = {
 	anthropic: SHAPES.anthropic,
 	google: SHAPES.google,
@@ -377,22 +384,32 @@ export function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "
  *  shapes carry their own `frameSize`. */
 export 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 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 const FRAME_TOKEN_ESTIMATE = 3300;
+/** 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 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 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 const FRAME_TOKEN_ESTIMATE = 5024;
 
 /**
- * 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).
+ * 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 const PROVIDER_IMAGE_BUDGETS: Record<string, number> = {
 	anthropic: 90,
@@ -402,7 +419,7 @@ export const PROVIDER_IMAGE_BUDGETS: Record<string, number> = {
 	google: 200,
 	"google-vertex": 200,
 	"google-gemini-cli": 200,
-	openrouter: 8,
+	openrouter: 90,
 };
 
 /** Safe floor for unknown providers (strictest mainstream measured: Groq ~5). */
@@ -413,11 +430,6 @@ export function providerImageBudget(provider: string | undefined): number {
 	return (provider !== undefined ? PROVIDER_IMAGE_BUDGETS[provider] : undefined) ?? DEFAULT_PROVIDER_IMAGE_BUDGET;
 }
 
-/** Archive frame budget for `provider`: its image budget clamped to {@link MAX_FRAMES}. */
-export function providerFrameBudget(provider: string | undefined): number {
-	return Math.min(MAX_FRAMES, providerImageBudget(provider));
-}
-
 /** Key under `CompactionEntry.preserveData` holding the frame archive. */
 export const PRESERVE_KEY = "snapcompact";
 
@@ -450,16 +462,20 @@ export interface Frame {
 
 /** Frame archive persisted under `preserveData[PRESERVE_KEY]`. */
 export interface Archive {
-	/** Frames ordered oldest to newest. */
+	/** 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. */
+	/** Characters currently readable across all frames plus the text regions. */
 	totalChars: number;
-	/** Characters dropped so far to respect the frame budget. */
+	/** Characters dropped so far to respect the archive 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. */
+	/** 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;
 }
 
@@ -481,7 +497,7 @@ export interface Options<TMessage = Message> extends SerializeOptions {
 	shape?: Shape;
 	/** Frame edge in pixels. Defaults to the shape's `frameSize`. */
 	frameSize?: number;
-	/** Frame budget. Defaults to {@link MAX_FRAMES}. */
+	/** Upper limit on archive frames; clamped to (and defaulting to) {@link MAX_FRAMES_DEFAULT}. */
 	maxFrames?: number;
 }
 
@@ -585,7 +601,7 @@ function stripFileOperationTags(summary: string): string {
 		.trimEnd();
 }
 
-function formatFileOperations(readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string {
+function formatFileList(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");
@@ -595,7 +611,12 @@ function formatFileOperations(readFiles: string[], modifiedFiles: string[], read
 	if (all.length > FILE_OPERATION_SUMMARY_LIMIT) {
 		files += `\n[…${all.length - FILE_OPERATION_SUMMARY_LIMIT} files elided…]`;
 	}
-	return prompt.render(fileOperationsTemplate, { files });
+	return files;
+}
+
+function formatFileOperations(readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string {
+	const files = formatFileList(readFiles, modifiedFiles, readSet);
+	return files.length > 0 ? prompt.render(fileOperationsTemplate, { files }) : "";
 }
 
 export function upsertFileOperations(
@@ -663,10 +684,11 @@ function truncateForSummary(text: string, maxChars: number, headRatio: number):
 
 const DIM_MARKERS = /[\u000e\u000f]/g;
 
-/** Cap on the unrendered archive text tail, in frame-capacity units: enough
- *  to keep the newest discarded history readable without re-inflating the
- *  context a compaction just shrank. */
-const TEXT_TAIL_MAX_PAGES = 2;
+/** Plain-text history kept verbatim at each chronological edge, in HQ-frame-
+ *  capacity units per edge. One page at the start and one at the end preserves
+ *  high-fidelity context around the imaged middle while keeping the total text
+ *  budget equal to the prior 2-page tail-only scheme. */
+const TEXT_EDGE_PAGES = 1;
 
 /** Normalized archive text → plain text: drop zero-width dim toggles and
  *  print newline glyphs as real newlines. */
@@ -1189,23 +1211,31 @@ export function getPreservedArchive(preserveData: Record<string, unknown> | unde
 	const candidate = preserveData?.[PRESERVE_KEY];
 	if (!candidate || typeof candidate !== "object") return undefined;
 	const archive = candidate as Archive;
-	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;
+	const frames = Array.isArray(archive.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",
+			)
+		: [];
+	const text = typeof archive.text === "string" && archive.text.length > 0 ? archive.text : undefined;
+	const textHead = typeof archive.textHead === "string" && archive.textHead.length > 0 ? archive.textHead : undefined;
+	const textTail = typeof archive.textTail === "string" && archive.textTail.length > 0 ? archive.textTail : undefined;
+	// A text-only archive (everything fit in the plain-text regions) is valid;
+	// only an archive carrying neither frames nor text is empty.
+	if (frames.length === 0 && text === undefined && textHead === undefined && textTail === undefined) return undefined;
 	return {
 		frames,
 		totalChars: typeof archive.totalChars === "number" ? archive.totalChars : 0,
 		truncatedChars: typeof archive.truncatedChars === "number" ? archive.truncatedChars : 0,
-		...(typeof archive.textTail === "string" && archive.textTail.length > 0 ? { textTail: archive.textTail } : {}),
+		...(text !== undefined ? { text } : {}),
+		...(textHead !== undefined ? { textHead } : {}),
+		...(textTail !== undefined ? { textTail } : {}),
 	};
 }
 
@@ -1218,28 +1248,176 @@ export function images(archive: Archive): ImageContent[] {
 		...(frame.detail ? { detail: frame.detail } : {}),
 	}));
 }
+/** 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 function historyBlocks(archive: Archive): (TextContent | ImageContent)[] {
+	const blocks: (TextContent | ImageContent)[] = [];
+	const hasImages = archive.frames.length > 0;
+	if (archive.textHead) {
+		const suffix = hasImages ? "\n-------------- imaged middle below\n" : "";
+		blocks.push({ type: "text", text: toPlainText(archive.textHead) + suffix });
+	}
+	blocks.push(...images(archive));
+	if (archive.textTail) {
+		const prefix = hasImages
+			? "-------------- imaged middle above\n"
+			: archive.truncatedChars > 0
+				? "\n-------------- middle history omitted above\n"
+				: "";
+		const tail = prefix + toPlainText(archive.textTail);
+		if (blocks.length > 0 && blocks[blocks.length - 1]?.type === "text") {
+			(blocks[blocks.length - 1] as TextContent).text += tail;
+		} else {
+			blocks.push({ type: "text", text: tail });
+		}
+	}
+	return blocks;
+}
 
 // ============================================================================
 // Compaction entry point
 // ============================================================================
 
+/** Denser companion of `high` for the foveated archive middle: same family and
+ *  frame size (identical per-frame bill) but a tighter cell. Returns `high`
+ *  unchanged for doc layouts or when no denser variant exists (foveation off). */
+function denseCompanion(high: Shape, api: Api | undefined): Shape {
+	if (high.columns === 2) return high;
+	const family = billingFamily(api);
+	const low = priceShape({ ...SHAPE_VARIANTS[FAMILY_VARIANT_LOW[family]], frameSize: high.frameSize }, family);
+	return geometry(low).capacity > geometry(high).capacity ? low : high;
+}
+
+/** One planned frame: the source slice and the shape (quality tier) to render. */
+interface PlanFrame {
+	text: string;
+	shape: Shape;
+}
+
+/** A foveated archive layout: frames oldest→newest for the imaged middle, the
+ *  verbatim text kept at both chronological edges, the flat kept source to
+ *  persist, and the chars dropped this round to fit the budget. */
+interface ArchiveLayout {
+	frames: PlanFrame[];
+	textHead: string;
+	textTail: string;
+	keptText: string;
+	truncatedChars: number;
+}
+
+/** Slice `text` into `capacity`-char frames at one shape (tier). */
+function sliceFrames(text: string, capacity: number, shape: Shape): PlanFrame[] {
+	const out: PlanFrame[] = [];
+	for (let offset = 0; offset < text.length; offset += capacity) {
+		out.push({ text: text.slice(offset, offset + capacity), shape });
+	}
+	return out;
+}
+
+/**
+ * Lay out the accumulated archive `text` (oldest→newest) with text at both
+ * chronological edges and images in the middle. One HQ-capacity stays verbatim
+ * at the oldest edge, one at the newest edge, and the middle between them is
+ * imaged. If the imaged middle itself overflows `maxFrames`, foveate it
+ * internally (HQ/LQ/HQ) and drop the oldest slice of its dense center.
+ */
+function planArchive(text: string, high: Shape, low: Shape, maxFrames: number): ArchiveLayout {
+	const capHi = geometry(high).capacity;
+	const edgeCap = TEXT_EDGE_PAGES * capHi;
+	if (text.length <= 2 * edgeCap) {
+		return { frames: [], textHead: text, textTail: "", keptText: text, truncatedChars: 0 };
+	}
+	if (maxFrames < 1) {
+		const textHead = text.slice(0, edgeCap);
+		const textTail = text.slice(text.length - edgeCap);
+		return {
+			frames: [],
+			textHead,
+			textTail,
+			keptText: textHead + textTail,
+			truncatedChars: text.length - textHead.length - textTail.length,
+		};
+	}
+
+	const textHead = text.slice(0, edgeCap);
+	const textTail = text.slice(text.length - edgeCap);
+	const imageText = text.slice(edgeCap, text.length - edgeCap);
+	if (imageText.length === 0) {
+		return { frames: [], textHead: text, textTail: "", keptText: text, truncatedChars: 0 };
+	}
+
+	// Doc layouts wrap (no char-slicing) and don't foveate: one tier, keep the
+	// newest pages with the session head pinned, drop the oldest middle.
+	if (high.columns === 2) {
+		const pages = docPages(imageText, geometry(high));
+		let kept = pages;
+		let truncatedChars = 0;
+		if (pages.length > maxFrames) {
+			const dropped = pages.slice(1, pages.length - (maxFrames - 1));
+			truncatedChars = dropped.reduce((sum, page) => sum + page.length, 0);
+			kept = [...pages.slice(0, 1), ...pages.slice(pages.length - (maxFrames - 1))];
+		}
+		const flat = kept.map(page => page.replaceAll("\n", " ")).join(" ");
+		return {
+			frames: kept.map(page => ({ text: page, shape: high })),
+			textHead,
+			textTail,
+			keptText: textHead + flat + textTail,
+			truncatedChars,
+		};
+	}
+
+	// Grid: render all-HQ when the image region fits the budget outright.
+	if (Math.ceil(imageText.length / capHi) <= maxFrames) {
+		return {
+			frames: sliceFrames(imageText, capHi, high),
+			textHead,
+			textTail,
+			keptText: textHead + imageText + textTail,
+			truncatedChars: 0,
+		};
+	}
+
+	// Foveate the imaged middle: HQ edges, dense center, drop the oldest dense slice.
+	const capLo = geometry(low).capacity;
+	const imageEdgeFrames = Math.min(HQ_EDGE_FRAMES, Math.floor((maxFrames - 1) / 2));
+	const imageEdgeCap = imageEdgeFrames * capHi;
+	const imageHead = imageText.slice(0, imageEdgeCap);
+	const imageTail = imageEdgeCap > 0 ? imageText.slice(imageText.length - imageEdgeCap) : "";
+	let middleText = imageText.slice(imageEdgeCap, imageText.length - imageEdgeCap);
+	let truncatedChars = 0;
+	const middleCap = (maxFrames - 2 * imageEdgeFrames) * capLo;
+	if (middleText.length > middleCap) {
+		truncatedChars = middleText.length - middleCap;
+		middleText = middleText.slice(truncatedChars);
+	}
+	return {
+		frames: [
+			...sliceFrames(imageHead, capHi, high),
+			...sliceFrames(middleText, capLo, low),
+			...sliceFrames(imageTail, capHi, high),
+		],
+		textHead,
+		textTail,
+		keptText: textHead + imageHead + middleText + imageTail + textTail,
+		truncatedChars,
+	};
+}
+
 /**
  * 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.
+ * 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.
  *
- * 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.
+ * 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 frame archive as `[Summary of earlier history]` so no continuity is lost.
+ * 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 async function compact<TMessage = Message>(
 	preparation: CompactionPreparation<TMessage>,
@@ -1249,10 +1427,14 @@ export async function compact<TMessage = Message>(
 	if (!firstKeptEntryId) {
 		throw new Error("First kept entry has no ID - session may need migration");
 	}
-	const shape = options?.shape ?? resolveShape(options?.model);
-	const frameSize = options?.frameSize ?? shape.frameSize;
-	const maxFrames = Math.max(1, options?.maxFrames ?? MAX_FRAMES);
-	const geo = geometry(shape, frameSize);
+	const baseShape = options?.shape ?? resolveShape(options?.model);
+	const frameSize = options?.frameSize ?? baseShape.frameSize;
+	const high = frameSize === baseShape.frameSize ? baseShape : { ...baseShape, frameSize };
+	const low = denseCompanion(high, options?.model?.api);
+	const geo = geometry(high);
+	// The engine default caps archive growth; a caller-supplied maxFrames only
+	// lowers it further (an upper limit), never raising it past the default.
+	const maxFrames = Math.max(1, Math.min(options?.maxFrames ?? MAX_FRAMES_DEFAULT, MAX_FRAMES_DEFAULT));
 
 	const messages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
 	const llmMessages = (options?.convertToLlm ?? defaultConvertToLlm)(messages);
@@ -1267,127 +1449,103 @@ export async function compact<TMessage = Message>(
 
 	let truncatedChars = previousArchive?.truncatedChars ?? 0;
 
-	// The previous compaction's unframed text tail is the oldest part of this
-	// archive slice — prepend it so it ages into frames first.
-	if (previousArchive?.textTail) {
-		archiveText =
-			archiveText.length > 0
-				? `${previousArchive.textTail}${NEWLINE_GLYPH}${archiveText}`
-				: previousArchive.textTail;
-	}
-
-	const pages: string[] = [];
-	if (shape.columns === 2) {
-		pages.push(...docPages(archiveText, geo));
-	} else {
-		for (let offset = 0; offset < archiveText.length; offset += geo.capacity) {
-			pages.push(archiveText.slice(offset, offset + geo.capacity));
-		}
+	// Re-compacting a snapcompacted history unfolds the prior archive's source
+	// text and treats it as one coherent transcript: the previous kept source
+	// ages in ahead of the new history, then the whole thing is re-rendered.
+	const previousText = previousArchive?.text;
+	if (previousText) {
+		archiveText = archiveText.length > 0 ? `${previousText}${NEWLINE_GLYPH}${archiveText}` : previousText;
 	}
 
-	// Fit the merged archive into the frame budget BEFORE rendering: pages
-	// that cannot ship are never rasterized. Old unpinned frames evict first
-	// (the archive fades oldest-first, as before); new pages that still do
-	// not fit stay behind as a verbatim text tail instead of being dropped.
-	const prevFrames = previousArchive?.frames ?? [];
-	let keptPrev = prevFrames;
-	if (prevFrames.length + pages.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.
-		// With a budget of one frame the pin is moot.
-		const pinCount = maxFrames >= 2 && prevFrames.length > 0 ? 1 : 0;
-		const evictable = prevFrames.slice(pinCount);
-		const surviving = Math.min(evictable.length, Math.max(0, maxFrames - pages.length - pinCount));
-		const dropped = evictable.slice(0, evictable.length - surviving);
-		for (const frame of dropped) truncatedChars += frame.chars;
-		keptPrev = [...prevFrames.slice(0, pinCount), ...evictable.slice(evictable.length - surviving)];
-	}
-	const renderPages = pages.slice(0, maxFrames - keptPrev.length);
-	const tailPages = pages.slice(renderPages.length);
+	const layout = planArchive(archiveText, high, low, maxFrames);
+	truncatedChars += layout.truncatedChars;
 
+	// Re-render the planned frames, carrying any open dim span across every
+	// boundary: textHead → frames → textTail.
+	let dimOpen = layout.textHead.lastIndexOf(DIM_ON) > layout.textHead.lastIndexOf(DIM_OFF);
 	const newFrames: Frame[] = [];
-	const finish = pageFinisher(shape);
-	for (const page of renderPages) {
-		const rendered = render(finish(page), shape, frameSize);
+	for (const planned of layout.frames) {
+		let pageText: string = dimOpen ? DIM_ON + planned.text : planned.text;
+		dimOpen = pageText.lastIndexOf(DIM_ON) > pageText.lastIndexOf(DIM_OFF);
+		if (planned.shape.stopwordDim) pageText = dimStopwords(pageText);
+		const rendered = render(pageText, planned.shape);
 		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.columns === 2 ? { columns: 2 } : {}),
-			...(shape.stopwordDim ? { stopwordDim: true } : {}),
-			...(shape.imageDetail ? { detail: shape.imageDetail } : {}),
+			font: planned.shape.font,
+			variant: planned.shape.variant,
+			lineRepeat: planned.shape.lineRepeat,
+			...(planned.shape.columns === 2 ? { columns: 2 } : {}),
+			...(planned.shape.stopwordDim ? { stopwordDim: true } : {}),
+			...(planned.shape.imageDetail ? { detail: planned.shape.imageDetail } : {}),
 		});
 		// Keep the event loop responsive between native render passes.
 		await Bun.sleep(0);
 	}
 
-	// Pages past the budget survive as text, capped at two frames' capacity
-	// (middle-elided) so an oversized archive cannot blow the context back up.
-	let textTail = "";
-	if (tailPages.length > 0) {
-		const raw =
-			shape.columns === 2 ? tailPages.map(page => page.replaceAll("\n", " ")).join(" ") : tailPages.join("");
-		const tailCap = TEXT_TAIL_MAX_PAGES * geo.capacity;
-		if (raw.length > tailCap) truncatedChars += raw.length - tailCap;
-		// Re-open a dim span the render boundary cut through, so the carried
-		// tail keeps tool output dim when it lands on frames next compaction.
-		const renderedText = shape.columns === 2 ? renderPages.join("\n") : renderPages.join("");
-		const dimOpen = renderedText.lastIndexOf(DIM_ON) > renderedText.lastIndexOf(DIM_OFF);
-		textTail = (dimOpen ? DIM_ON : "") + truncateForSummary(raw, tailCap, TRUNCATE_HEAD_RATIO);
-	}
+	const textHead = layout.textHead;
+	const textTail = layout.textTail.length > 0 ? (dimOpen ? DIM_ON : "") + layout.textTail : "";
+	const textChars = textHead.length + textTail.length;
 
-	const frames = [...keptPrev, ...newFrames];
-	const totalChars = frames.reduce((sum, frame) => sum + frame.chars, 0);
+	const frames = newFrames;
+	const totalChars = frames.reduce((sum, frame) => sum + frame.chars, 0) + textChars;
 	const mixedShapes = frames.some(
 		frame =>
 			frame.cols !== geo.cols ||
 			frame.rows !== geo.rows ||
-			(frame.variant ?? "sent") !== shape.variant ||
-			(frame.lineRepeat ?? 1) !== shape.lineRepeat ||
-			(frame.columns ?? 1) !== (shape.columns ?? 1) ||
-			(frame.stopwordDim ?? false) !== (shape.stopwordDim ?? false),
+			(frame.variant ?? "sent") !== high.variant ||
+			(frame.lineRepeat ?? 1) !== high.lineRepeat ||
+			(frame.columns ?? 1) !== (high.columns ?? 1) ||
+			(frame.stopwordDim ?? false) !== (high.stopwordDim ?? false),
 	);
 
+	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+	const files = formatFileList(readFiles, modifiedFiles, fileOps.read);
+
 	let summary: string;
-	if (frames.length === 0) {
+	if (frames.length === 0 && textHead.length === 0 && textTail.length === 0 && files.length === 0) {
 		summary = "No prior history.";
 	} else {
 		summary = prompt.render(snapcompactSummaryPrompt, {
 			frameCount: frames.length,
 			multipleFrames: frames.length > 1,
-			fontCell: `${shape.cellWidth}x${shape.cellHeight}`,
+			docColumns: high.columns === 2,
 			cols: geo.cols,
 			rows: geo.rows,
-			sentenceInk: shape.variant === "sent",
-			lineRepeated: shape.lineRepeat > 1,
-			docColumns: shape.columns === 2,
-			stopwordDimmed: shape.stopwordDim === true,
+			sentenceInk: high.variant === "sent",
+			stopwordDimmed: high.stopwordDim === true,
 			dimmedToolResults: options?.dimToolResults !== false,
+			lineRepeated: high.lineRepeat > 1,
 			mixedShapes,
-			totalChars,
 			truncatedChars,
 			includedPreviousSummary,
-			textTail: textTail.length > 0 ? toPlainText(textTail) : undefined,
+			files: files.length > 0 ? files : undefined,
 		});
 	}
-	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
-	summary = upsertFileOperations(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: Archive = { frames, totalChars, truncatedChars, ...(textTail ? { textTail } : {}) };
+	const persistedText =
+		layout.keptText.length > 0 && layout.textTail.length > 0
+			? `${layout.keptText.slice(0, layout.keptText.length - layout.textTail.length)}${textTail}`
+			: layout.keptText;
+	const archive: Archive = {
+		frames,
+		totalChars,
+		truncatedChars,
+		...(persistedText.length > 0 ? { text: persistedText } : {}),
+		...(textHead ? { textHead } : {}),
+		...(textTail ? { textTail } : {}),
+	};
 
-	const textTailNote = textTail ? ` (+${textTail.length.toLocaleString()} chars as text)` : "";
+	const textNote = textChars > 0 ? ` (+${textChars.toLocaleString()} chars as text)` : "";
 	return {
 		summary,
-		shortSummary: `Archived ${totalChars.toLocaleString()} chars of history onto ${frames.length} snapcompact frame${frames.length === 1 ? "" : "s"}${textTailNote}`,
+		shortSummary: `Archived ${totalChars.toLocaleString()} chars of history onto ${frames.length} snapcompact frame${frames.length === 1 ? "" : "s"}${textNote}`,
 		firstKeptEntryId,
 		tokensBefore,
 		details: { readFiles, modifiedFiles },