@oh-my-pi/snapcompact 15.11.6 → 15.11.8

package/src/snapcompact.ts

@@ -2,27 +2,40 @@
  * 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.
+ * conversation is rendered into PNG frames of pixel-font text that vision
+ * models read back directly, like an archivist at a snapcompact frame
+ * reader. Frames are `frameSize` wide; their height hugs the text rows
+ * actually printed, so a partially filled frame never bills blank rows.
  *
  * The frame shape is provider-aware, 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.
+ * - **Anthropic** (`6x12-dim`): X.org 6x12 glyphs, black ink, stopwords
+ *   dimmed gray — recall within noise of the repeated `8x8r-bw` grid at
+ *   ~40% lower cost; `8x8r-bw` remains the max-recall choice via the shape
+ *   setting. Opus 4.7+/Fable/Mythos ingest high-res natively (2576px edge,
+ *   4,784 visual-token cap, no flag needed), so those lines get 1932px
+ *   frames: same recall and cost, a third fewer frames. Older Claude lines
+ *   downscale past 1568px and keep the standard frame.
+ * - **Google** (`doc-8on16-sent-dim` @2048): two word-wrapped newspaper
+ *   columns of 8x13 glyphs, sentence-hue ink, dimmed stopwords. Gemini 3.x
+ *   bills a fixed `media_resolution` budget per image (default 1,120
+ *   tokens) regardless of pixels, so the 2048px frame carries +70% chars at
+ *   the same bill (f1 .88 vs .90 at 1568). `ULTRA_HIGH` doubles the budget
+ *   and reads 3072px frames, but loses on chars/$ — deliberately unused.
+ * - **OpenAI** (`8on16-bw`): 8x13 glyphs on a patch-aligned 16px pitch,
+ *   black ink (gpt-5.5 mono F1 .867 vs .602 for the previous `6x6u-sent`).
+ *   Patch billing (32px × 1.2, 10k-patch budget at `detail: "original"`) is
+ *   area-proportional, so resolution cannot improve chars/$ — 1568 stays.
+ *   `detail: "high"` would downgrade (2,500-patch cap); `original` is sent.
+ * - **Unknown providers** default to the Anthropic shape. Gateways can
+ *   defeat any shape silently: OpenRouter enforces a per-model image cap
+ *   (measured: 8 images for glm-4.6v — frames past the cap are dropped with
+ *   no error, billed tokens plateau exactly at 8x frame cost). The same
+ *   frames routed direct to the vendor read fine (glm f1 .20 -> .78), so
+ *   `providerImageBudget` caps per-request images per provider (OpenRouter
+ *   8, unknown 5) and `compact()` keeps any archive overflow as a text tail
+ *   on the summary instead of rendering frames that would be dropped.
  *
  * The whole pass is local and deterministic — no LLM call, no API key, no
  * latency beyond rendering. Rasterization and PNG encoding happen in native
@@ -44,14 +57,22 @@ import snapcompactSummaryPrompt from "./prompts/snapcompact-summary.md" with { t
 /** One eval-validated frame shape: font, cell, ink, repetition, and size. */
 export interface Shape {
 	/** Bundled font in the native renderer. */
-	font: "5x8" | "8x8";
+	font: "5x8" | "8x8" | "6x12" | "8x13";
 	/** Target cell advance in pixels; differing from the font's natural cell
 	 *  renders via Lanczos stretch (anti-aliased RGB frame). */
 	cellWidth: number;
 	/** Target cell pitch in pixels. */
 	cellHeight: number;
+	/** `false` → glyphs drawn at natural size on the cell pitch (8on16);
+	 *  `true`/`undefined` → legacy auto Lanczos stretch when cell ≠ natural. */
+	stretch?: boolean;
 	/** Ink: `sent` cycles six hues at sentence boundaries; `bw` is black. */
 	variant: "sent" | "bw";
+	/** Print stopwords in dim ink (research `dim`/`sent-dim` variants). */
+	stopwordDim?: boolean;
+	/** 1/undefined = row-major grid; 2 = two word-wrapped newspaper columns
+	 *  (research `doc`). */
+	columns?: number;
 	/** Each text line is printed this many times; copies after the first sit
 	 *  on a pale highlight band (redundancy coding). */
 	lineRepeat: number;
@@ -63,51 +84,162 @@ export interface Shape {
 	imageDetail?: ImageContent["detail"];
 }
 
-/** Eval-validated shapes, keyed by the provider family they won on. */
-export const SHAPES = {
-	/** `8x8r-bw`: unscii square, black ink, lines doubled on highlight bands. */
-	anthropic: {
-		font: "8x8",
+/** Geometry half of a {@link Shape}: everything except provider billing. */
+export type ShapeGeometry = Omit<Shape, "frameTokenEstimate" | "imageDetail">;
+
+/**
+ * Frame variants exercised by the SQuAD evals in `research/` that the native
+ * renderer reproduces faithfully, keyed by their research names. Font codes:
+ * `8x8u` unscii square cell, `8x8r` unscii with every line printed twice
+ * (redundancy coding), `6x6u` unscii Lanczos-squeezed to 6x6 (densest
+ * readable cell), `5x8` the X.org legacy font on its 2576px frame, `6x12`
+ * and `8x13` the X.org misc fonts, `8on16` 8x13 glyphs on an 8x16 cell pitch
+ * (no stretch, extra leading), `doc-` prefixed shapes a two-column
+ * word-wrapped newspaper layout. Ink: `sent` cycles six hues at sentence
+ * boundaries, `bw` is plain black, `-dim` suffix prints stopwords in gray.
+ */
+export const SHAPE_VARIANTS = {
+	"8x8r-bw": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "bw", lineRepeat: 2, frameSize: 1568 },
+	"8x8r-sent": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "sent", lineRepeat: 2, frameSize: 1568 },
+	"8x8u-bw": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "bw", lineRepeat: 1, frameSize: 1568 },
+	"8x8u-sent": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "sent", lineRepeat: 1, frameSize: 1568 },
+	"6x6u-bw": { font: "8x8", cellWidth: 6, cellHeight: 6, variant: "bw", lineRepeat: 1, frameSize: 1568 },
+	"6x6u-sent": { font: "8x8", cellWidth: 6, cellHeight: 6, variant: "sent", lineRepeat: 1, frameSize: 1568 },
+	"5x8-bw": { font: "5x8", cellWidth: 5, cellHeight: 8, variant: "bw", lineRepeat: 1, frameSize: 2576 },
+	"5x8-sent": { font: "5x8", cellWidth: 5, cellHeight: 8, variant: "sent", lineRepeat: 1, frameSize: 2576 },
+	"6x12-dim": {
+		font: "6x12",
+		cellWidth: 6,
+		cellHeight: 12,
+		variant: "bw",
+		stopwordDim: true,
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"8x13-bw": { font: "8x13", cellWidth: 8, cellHeight: 13, variant: "bw", lineRepeat: 1, frameSize: 1568 },
+	"8on16-bw": {
+		font: "8x13",
 		cellWidth: 8,
-		cellHeight: 8,
+		cellHeight: 16,
+		stretch: false,
 		variant: "bw",
-		lineRepeat: 2,
+		lineRepeat: 1,
 		frameSize: 1568,
-		frameTokenEstimate: 3300,
 	},
-	/** `8x8r-sent`: the repeated grid with sentence-hue ink. */
-	google: {
-		font: "8x8",
+	"doc-8on16-bw": {
+		font: "8x13",
 		cellWidth: 8,
-		cellHeight: 8,
-		variant: "sent",
-		lineRepeat: 2,
+		cellHeight: 16,
+		stretch: false,
+		variant: "bw",
+		columns: 2,
+		lineRepeat: 1,
 		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,
+	"doc-8on16-sent": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 16,
+		stretch: false,
 		variant: "sent",
+		columns: 2,
 		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,
+	"doc-8on16-sent-dim": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 16,
+		stretch: false,
 		variant: "sent",
+		stopwordDim: true,
+		columns: 2,
 		lineRepeat: 1,
-		frameSize: 2576,
-		frameTokenEstimate: 3300,
+		frameSize: 1568,
 	},
-} as const satisfies Record<string, Shape>;
+} as const satisfies Record<string, ShapeGeometry>;
+
+/** Research name of one renderable frame variant. */
+export type ShapeVariantName = keyof typeof SHAPE_VARIANTS;
+
+/** All variant names, in declaration order (for settings enums). */
+export const SHAPE_VARIANT_NAMES = Object.keys(SHAPE_VARIANTS) as readonly ShapeVariantName[];
+
+/** Runtime guard for variant names loaded from config. */
+export function isShapeVariantName(value: unknown): value is ShapeVariantName {
+	return typeof value === "string" && value in SHAPE_VARIANTS;
+}
+
+/** Provider families with distinct image billing. */
+type BillingFamily = "anthropic" | "google" | "openai";
+
+function billingFamily(api?: Api): BillingFamily {
+	switch (api) {
+		case "openai-completions":
+		case "openai-responses":
+		case "openai-codex-responses":
+		case "azure-openai-responses":
+			return "openai";
+		case "google-generative-ai":
+		case "google-gemini-cli":
+		case "google-vertex":
+			return "google";
+		default:
+			// anthropic-messages, bedrock-converse-stream, and anything unknown
+			// share Anthropic's pixel-area pricing as the safe ceiling.
+			return "anthropic";
+	}
+}
+
+/**
+ * Per-frame billing for a square frame of edge `frameSize`, by family.
+ * Formulas verified against live bills in the resolution benchmarks:
+ * - Anthropic: 28px patches, capped at 4,784 visual tokens (the API
+ *   downscales past the cap; 1568 → 3,136 measured) + 5% margin.
+ * - Google: Gemini 3.x bills a fixed `media_resolution` budget per image —
+ *   default HIGH = 1,120 tokens — regardless of pixel size.
+ * - OpenAI: 32px patches × 1.2 flagship multiplier, 10,000-patch budget at
+ *   `detail: "original"` (1568 → 2,881 measured).
+ */
+function familyBilling(family: BillingFamily, frameSize: number): Pick<Shape, "frameTokenEstimate" | "imageDetail"> {
+	switch (family) {
+		case "google":
+			return { frameTokenEstimate: 1120 };
+		case "openai": {
+			const patches = Math.min(Math.ceil(frameSize / 32) ** 2, 10_000);
+			return { frameTokenEstimate: Math.ceil(patches * 1.2), imageDetail: "original" };
+		}
+		default: {
+			const patches = Math.min(Math.ceil(frameSize / 28) ** 2, 4784);
+			return { frameTokenEstimate: Math.ceil(patches * 1.05) };
+		}
+	}
+}
+
+/** Attach a provider family's billing to a variant geometry. */
+function priceShape(base: ShapeGeometry, family: BillingFamily): Shape {
+	return { ...base, ...familyBilling(family, base.frameSize) };
+}
+
+/** Eval-validated shapes, keyed by the provider family they won on. */
+export const SHAPES = {
+	/** `6x12-dim`: X.org 6x12 glyphs, black ink with stopwords dimmed gray.
+	 *  Production mono eval on claude-fable: f1 .840 vs .877 for the repeated
+	 *  `8x8r-bw` grid (within noise at n=25) at 37% lower cost — 12 frames
+	 *  instead of 21 per 400k chars. Never refused in any run. */
+	anthropic: priceShape(SHAPE_VARIANTS["6x12-dim"], "anthropic"),
+	/** `doc-8on16-sent-dim`: two word-wrapped columns, sentence hues, dimmed
+	 *  stopwords. Production mono eval on gemini-3.5-flash: f1 .900 vs .853
+	 *  for the repeated grid, at lower cost; also the chunked round-2 winner. */
+	google: priceShape(SHAPE_VARIANTS["doc-8on16-sent-dim"], "google"),
+	/** `8on16-bw`: 8x13 X.org glyphs on a 16px pitch, black ink. Mono eval on
+	 *  gpt-5.5 (200k-token single request, n=50): f1 .851 vs .602 for the
+	 *  previous `6x6u-sent` default at near-equal total cost; chunked exp14
+	 *  scored it .906. */
+	openai: priceShape(SHAPE_VARIANTS["8on16-bw"], "openai"),
+	/** Original 5x8 X.org shape (pre-shape-table sessions rendered this). */
+	legacy: priceShape(SHAPE_VARIANTS["5x8-sent"], "anthropic"),
+} satisfies Record<string, Shape>;
 
 /** Runtime guard for shape overrides loaded from config or preserve data. */
 export function isShape(value: unknown): value is Shape {
@@ -117,12 +249,15 @@ export function isShape(value: unknown): value is Shape {
 	const variant = shape.variant;
 	const detail = shape.imageDetail;
 	return (
-		(font === "5x8" || font === "8x8") &&
+		(font === "5x8" || font === "8x8" || font === "6x12" || font === "8x13") &&
 		typeof shape.cellWidth === "number" &&
 		shape.cellWidth > 0 &&
 		typeof shape.cellHeight === "number" &&
 		shape.cellHeight > 0 &&
+		(shape.stretch === undefined || typeof shape.stretch === "boolean") &&
 		(variant === "sent" || variant === "bw") &&
+		(shape.stopwordDim === undefined || typeof shape.stopwordDim === "boolean") &&
+		(shape.columns === undefined || shape.columns === 1 || shape.columns === 2) &&
 		typeof shape.lineRepeat === "number" &&
 		shape.lineRepeat > 0 &&
 		typeof shape.frameSize === "number" &&
@@ -133,23 +268,80 @@ export function isShape(value: unknown): value is Shape {
 	);
 }
 
-/** Pick the eval-optimal frame shape for a provider API. */
-export function resolveShape(api?: Api): Shape {
-	switch (api) {
-		case "openai-completions":
-		case "openai-responses":
-		case "openai-codex-responses":
-		case "azure-openai-responses":
-			return SHAPES.openaiDense;
-		case "google-generative-ai":
-		case "google-gemini-cli":
-		case "google-vertex":
-			return SHAPES.google;
-		default:
-			// anthropic-messages, bedrock-converse-stream, and anything unknown:
-			// the plain repeated grid is the most refusal-robust reader shape.
-			return SHAPES.anthropic;
-	}
+/** Eval-winning variant per provider family (billing fallback when the
+ *  model id matches no known reader line). */
+const FAMILY_VARIANT: Record<BillingFamily, ShapeVariantName> = {
+	anthropic: "6x12-dim",
+	google: "doc-8on16-sent-dim",
+	openai: "8on16-bw",
+};
+
+const FAMILY_SHAPE: Record<BillingFamily, Shape> = {
+	anthropic: SHAPES.anthropic,
+	google: SHAPES.google,
+	openai: SHAPES.openai,
+};
+
+/** One model line's ideal format: variant plus an optional frame-size
+ *  override when the line reads larger frames at no extra cost. */
+export interface IdealShape {
+	variant: ShapeVariantName;
+	frameSize?: number;
+}
+
+/** Eval-winning format per model line, matched against the model id. The
+ *  wire API only identifies the gateway — a Claude served through Vertex or
+ *  OpenRouter still reads best with its own shape. Patterns cover the model
+ *  lines the mono evals measured; everything else falls back to the API
+ *  family's winner at the standard 1568px frame. First match wins. */
+const MODEL_VARIANTS: readonly (readonly [RegExp, IdealShape])[] = [
+	// Opus 4.7+ and Fable/Mythos read high-res natively (2576px edge under a
+	// 4,784 visual-token cap → 1932px square sweet spot): same recall and
+	// cost as 1568, a third fewer frames (12 → 8 per 400k chars).
+	[/claude.*(fable|mythos)/i, { variant: "6x12-dim", frameSize: 1932 }],
+	[/claude-?opus-?4[.-][7-9]/i, { variant: "6x12-dim", frameSize: 1932 }],
+	// Older Claude lines downscale past 1568px — keep the safe size.
+	[/claude/i, { variant: "6x12-dim" }],
+	// Gemini 3.x bills a fixed 1,120-token budget per image regardless of
+	// pixels: 2048px packs +70% chars per frame at the same bill.
+	[/gemini/i, { variant: "doc-8on16-sent-dim", frameSize: 2048 }],
+	// gpt-5.5 patch billing is area-proportional; 1568 is already optimal.
+	[/gpt|codex/i, { variant: "8on16-bw" }],
+	// kimi's image processor downscales past 1792px (64×64 28px patches);
+	// 1568 wins on chars/$ and reads at f1 .973 (≤8 frames per request).
+	[/kimi/i, { variant: "8on16-bw" }],
+	// glm-4.6v .780 mono via direct vendor routing.
+	[/glm/i, { variant: "8on16-bw" }],
+];
+
+/** Eval-ideal format for a model id, or undefined when unmeasured. */
+export function idealShapeVariant(modelId: string): IdealShape | undefined {
+	return MODEL_VARIANTS.find(([pattern]) => pattern.test(modelId))?.[1];
+}
+
+/** What will read the frames: the wire API (billing) and model id (shape). */
+export interface ShapeTarget {
+	api?: Api;
+	id?: string;
+}
+
+/**
+ * Pick the frame shape for a reader. An explicit `variant` (anything but
+ * `"auto"`) forces that geometry; otherwise the model id selects the
+ * eval-winning shape — and frame size — for its model line, falling back to
+ * the API family's winner when the model is unmeasured. Billing (token
+ * estimate, detail hint) always follows the API family actually carrying
+ * the request, computed for the resolved frame size. Accepts a full pi-ai
+ * `Model` or any `{ api, id }` subset.
+ */
+export function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape {
+	const family = billingFamily(model?.api);
+	if (variant && variant !== "auto") return priceShape(SHAPE_VARIANTS[variant], family);
+	const ideal = model?.id ? idealShapeVariant(model.id) : undefined;
+	const name = ideal?.variant ?? FAMILY_VARIANT[family];
+	if (name === FAMILY_VARIANT[family] && ideal?.frameSize === undefined) return FAMILY_SHAPE[family];
+	const base = SHAPE_VARIANTS[name];
+	return priceShape(ideal?.frameSize ? { ...base, frameSize: ideal.frameSize } : base, family);
 }
 
 // ============================================================================
@@ -169,6 +361,37 @@ export const MAX_FRAMES = 8;
  *  (upper bound across shapes: Anthropic bills 1568*1568/750 ≈ 3,278). */
 export const FRAME_TOKEN_ESTIMATE = 3300;
 
+/**
+ * Per-request image-count budgets by provider id. Routers and smaller
+ * providers enforce hard caps and silently DROP images past them (measured:
+ * OpenRouter caps at 8 — images 9+ vanish with no error and billed tokens
+ * plateau at 8x frame cost). First-party APIs allow far more; their values
+ * are conservative policy caps well under the measured hard limits
+ * (Anthropic 100, OpenAI 500, Gemini ~2500).
+ */
+export const PROVIDER_IMAGE_BUDGETS: Record<string, number> = {
+	anthropic: 90,
+	"amazon-bedrock": 90,
+	openai: 200,
+	google: 200,
+	"google-vertex": 200,
+	"google-gemini-cli": 200,
+	openrouter: 8,
+};
+
+/** Safe floor for unknown providers (strictest mainstream measured: Groq ~5). */
+export const DEFAULT_PROVIDER_IMAGE_BUDGET = 5;
+
+/** Per-request image budget for `provider`; unknown providers get the floor. */
+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";
 
@@ -181,7 +404,7 @@ export interface Frame {
 	/** Base64-encoded PNG. */
 	data: string;
 	mimeType: string;
-	/** Characters per row in the frame grid. */
+	/** Characters per row in the frame grid (per-column width on doc frames). */
 	cols: number;
 	/** Text rows in the frame grid (unique lines, not repeated copies). */
 	rows: number;
@@ -191,6 +414,10 @@ export interface Frame {
 	font?: Shape["font"];
 	variant?: Shape["variant"];
 	lineRepeat?: number;
+	/** 2 on two-column doc frames; absent on row-major grid frames. */
+	columns?: number;
+	/** True when stopwords were printed in dim ink. */
+	stopwordDim?: boolean;
 	/** Resolution hint forwarded to the provider when re-attaching. */
 	detail?: ImageContent["detail"];
 }
@@ -203,12 +430,19 @@ export interface Archive {
 	totalChars: number;
 	/** Characters dropped so far to respect the frame budget. */
 	truncatedChars: number;
+	/** Most recent slice of archived history that exceeded the frame budget,
+	 *  kept verbatim as normalized text (dim markers and newline glyphs
+	 *  included). Shipped as plain text in the compaction summary and folded
+	 *  back into frames by the next compaction. */
+	textTail?: string;
 }
 
 export interface Geometry {
+	/** Characters per row (per-column line width when `columns === 2`). */
 	cols: number;
 	rows: number;
-	/** Characters that fit one frame (cols * rows). */
+	/** Characters that fit one frame (nominal upper bound on doc shapes,
+	 *  where real consumption is wrap-dependent). */
 	capacity: number;
 }
 
@@ -396,6 +630,17 @@ 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;
+
+/** Normalized archive text → plain text: drop zero-width dim toggles and
+ *  print newline glyphs as real newlines. */
+function toPlainText(text: string): string {
+	return stripDimMarkers(text).replaceAll(NEWLINE_GLYPH, "\n");
+}
+
 /** Strip stray ink toggles from raw content so it cannot forge dim spans. */
 function stripDimMarkers(text: string): string {
 	return text.replace(DIM_MARKERS, "");
@@ -517,18 +762,52 @@ const CHAR_FOLD: Record<string, string> = {
 	"\u2718": "x",
 };
 
+/** Printed in place of newline runs: the native renderer fills this cell
+ *  entirely with pitch-black ink, so line structure survives whitespace
+ *  collapsing at a one-cell cost. */
+export const NEWLINE_GLYPH = "\u2588";
+
+/** Collapsed in one pass: whitespace plus zero-width format characters (ZWSP,
+ *  BOM, directional marks — JS `\s` already counts BOM as whitespace, so they
+ *  must fold here, before the per-character pass). */
+const COLLAPSIBLE = /[\s\p{Cf}]+/gu;
+
+/** Runs carrying one of these collapse to {@link NEWLINE_GLYPH}. */
+const LINE_BREAK = /[\n\r\u2028\u2029]/;
+
+/** Leading/trailing spaces or newline glyphs add no information to a frame. */
+const EDGE_RUNS = /^[ \u2588]+|[ \u2588]+$/g;
+
+/** Glyph-less code points skipped outright instead of printing `?`: controls
+ *  (bare ESC/BEL/NUL — full ANSI sequences are stripped beforehand),
+ *  combining marks the fonts cannot compose, and lone surrogates. */
+const UNRENDERABLE = /[\p{Cc}\p{Mn}\p{Me}\p{Cs}]/u;
+
 /**
- * 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).
+ * Prepare text for printing: strip ANSI escape sequences, collapse horizontal
+ * whitespace runs to single spaces and newline-bearing runs to one
+ * {@link NEWLINE_GLYPH} (drawn as a pitch-black cell), then fold everything
+ * outside the fonts' ASCII + Latin-1 coverage to ASCII approximations.
+ * Unrenderable control/format/combining characters are dropped without
+ * occupying a cell; `?` remains the fallback for unsupported graphic
+ * characters. The zero-width ink toggles {@link DIM_ON}/{@link DIM_OFF} pass
+ * through untouched.
  */
 export function normalize(text: string): string {
-	const collapsed = text.replace(/\s+/g, " ").trim();
+	const stripped = text.includes("\u001b") ? Bun.stripANSI(text) : text;
+	const collapsed = stripped
+		// A run of pure format chars (BOM is both \s and Cf) vanishes; only a
+		// run containing genuine whitespace separates words.
+		.replace(COLLAPSIBLE, run => (LINE_BREAK.test(run) ? NEWLINE_GLYPH : /[^\p{Cf}]/u.test(run) ? " " : ""))
+		.replace(EDGE_RUNS, "");
 	let out = "";
 	for (const ch of collapsed) {
 		const cp = ch.codePointAt(0) as number;
-		if (cp < 0x7f || (cp >= 0xa0 && cp <= 0xff)) {
+		if ((cp >= 0x20 && cp < 0x7f) || (cp >= 0xa0 && cp <= 0xff)) {
+			out += ch;
+			continue;
+		}
+		if (ch === DIM_ON || ch === DIM_OFF || ch === NEWLINE_GLYPH) {
 			out += ch;
 			continue;
 		}
@@ -538,39 +817,167 @@ export function normalize(text: string): string {
 		} else if (cp >= 0x2500 && cp <= 0x257f) {
 			// Box drawing: keep table skeletons legible.
 			out += cp === 0x2502 || cp === 0x2503 ? "|" : cp === 0x2500 || cp === 0x2501 ? "-" : "+";
-		} else {
+		} else if (!UNRENDERABLE.test(ch)) {
 			out += "?";
 		}
 	}
 	return out;
 }
 
+// ============================================================================
+// Stopword dimming
+// ============================================================================
+
+/** High-frequency function words a reader can reconstruct from context; the
+ *  dim shapes render them in light gray so content words carry the contrast
+ *  (verbatim from `research/bdf.py` `_STOPWORDS`). */
+const STOPWORDS: ReadonlySet<string> = new Set(
+	(
+		"the a an and or of to in on at as is are was were be been by for with that this it its from had has have not but " +
+		"he she his her they their them which also who whom when where while will would could should there then than " +
+		"into over under about after before between during each such these those some most more other only same so"
+	).split(" "),
+);
+
+/** Maximal alphabetic runs (ASCII + Latin-1 letters, the fonts' coverage). */
+const ALPHA_RUN = /[a-zA-Z\u00c0-\u00d6\u00d8-\u00f6\u00f8-\u00ff]+/g;
+
+/** Splitter that keeps the zero-width ink toggles as their own segments. */
+const DIM_MARKER_SPLIT = /([\u000e\u000f])/;
+
+/**
+ * Wrap each maximal alphabetic run that is a stopword in {@link DIM_ON} /
+ * {@link DIM_OFF} so it prints in dim gray ink. Spans that are already dim
+ * (e.g. archived tool output) pass through untouched — wrapping there would
+ * terminate the enclosing dim span early. Markers are zero-width, so the
+ * visible glyph count is unchanged.
+ */
+export function dimStopwords(text: string): string {
+	const parts = text.split(DIM_MARKER_SPLIT);
+	let dim = false;
+	let out = "";
+	for (const part of parts) {
+		if (part === DIM_ON) {
+			dim = true;
+			out += part;
+		} else if (part === DIM_OFF) {
+			dim = false;
+			out += part;
+		} else if (dim) {
+			out += part;
+		} else {
+			out += part.replace(ALPHA_RUN, word => (STOPWORDS.has(word.toLowerCase()) ? DIM_ON + word + DIM_OFF : word));
+		}
+	}
+	return out;
+}
+
+// ============================================================================
+// Doc layout (two word-wrapped newspaper columns)
+// ============================================================================
+
+/** Char cells between the two doc columns (research exp14 `GUTTER`). */
+const DOC_GUTTER = 3;
+
+/**
+ * Greedy word-wrap, no mid-word breaks (hard split only for width+ words) —
+ * ported verbatim from `research/exp14_bestgpt.py` `wrap()`. Zero-width dim
+ * markers count toward word length here; serialized history places them at
+ * word boundaries, so the drift is at most one cell per affected line.
+ */
+export function wrap(text: string, width: number): string[] {
+	const lines: string[] = [];
+	let cur = "";
+	for (const token of text.split(/\s+/)) {
+		if (token.length === 0) continue;
+		let word = token;
+		while (word.length > width) {
+			// Pathological; never hit on prose.
+			if (cur) {
+				lines.push(cur);
+				cur = "";
+			}
+			lines.push(word.slice(0, width));
+			word = word.slice(width);
+		}
+		if (!cur) {
+			cur = word;
+		} else if (cur.length + 1 + word.length <= width) {
+			cur += ` ${word}`;
+		} else {
+			lines.push(cur);
+			cur = word;
+		}
+	}
+	if (cur) lines.push(cur);
+	return lines;
+}
+
+/**
+ * Paginate already-normalized text for a doc shape: wrap once at the column
+ * width, then slice into pages of `2 * rows` lines, each page `\n`-joined.
+ * Every input character lands on exactly one page (whitespace becomes the
+ * wrap points).
+ */
+function docPages(normalized: string, geo: Geometry): string[] {
+	const lines = wrap(normalized, geo.cols);
+	const perPage = 2 * geo.rows;
+	const pages: string[] = [];
+	for (let offset = 0; offset < lines.length; offset += perPage) {
+		pages.push(lines.slice(offset, offset + perPage).join("\n"));
+	}
+	return pages;
+}
+
 // ============================================================================
 // Rendering
 // ============================================================================
 
 export function geometry(shape: Shape, size: number = shape.frameSize): Geometry {
-	const cols = Math.floor(size / shape.cellWidth);
+	const gridCols = Math.floor(size / shape.cellWidth);
 	const rows = Math.floor(size / shape.cellHeight / shape.lineRepeat);
-	return { cols, rows, capacity: cols * rows };
+	if (shape.columns === 2) {
+		const cols = Math.floor((gridCols - DOC_GUTTER) / 2);
+		return { cols, rows, capacity: 2 * cols * rows };
+	}
+	return { cols: gridCols, rows, capacity: gridCols * rows };
 }
 
-/** Render one snapcompact frame from already-normalized text. */
+const NEWLINES = /\n/g;
+
+/** Render one snapcompact frame from already-normalized text. Doc shapes
+ *  (`columns === 2`) expect one page of `\n`-joined pre-wrapped lines. */
 export function render(text: string, shape: Shape, size: number = shape.frameSize): RenderedFrame {
 	const { cols, rows, capacity } = geometry(shape, size);
-	const visible = text.length - (text.match(DIM_MARKERS)?.length ?? 0);
+	let visible = text.length - (text.match(DIM_MARKERS)?.length ?? 0);
+	// Doc line separators consume no cell; in the grid they print as a blank.
+	if (shape.columns === 2) visible -= text.match(NEWLINES)?.length ?? 0;
 	const chars = Math.min(visible, capacity);
 	const data = renderSnapcompactPng(text, {
 		size,
 		font: shape.font,
 		cellWidth: shape.cellWidth,
 		cellHeight: shape.cellHeight,
+		stretch: shape.stretch,
 		variant: shape.variant,
 		lineRepeat: shape.lineRepeat,
+		columns: shape.columns,
 	});
 	return { data, cols, rows, chars };
 }
 
+/** Stateful per-page text finisher: re-opens a dim span the previous page
+ *  boundary cut through, then applies stopword dimming when the shape asks
+ *  for it (after pagination, so capacity math never sees the markers). */
+function pageFinisher(shape: Shape): (page: string) => string {
+	let dimOpen = false;
+	return page => {
+		const text = dimOpen ? DIM_ON + page : page;
+		dimOpen = text.lastIndexOf(DIM_ON) > text.lastIndexOf(DIM_OFF);
+		return shape.stopwordDim ? dimStopwords(text) : text;
+	};
+}
+
 /** Options for {@link renderMany} and {@link frames}. */
 export interface RenderManyOptions {
 	/** Explicit shape; wins over `model`. */
@@ -589,29 +996,45 @@ export interface RenderManyOptions {
  * Empty/whitespace-only input yields no frames.
  */
 export function renderMany(text: string, options?: RenderManyOptions): ImageContent[] {
-	const shape = options?.shape ?? resolveShape(options?.model?.api);
+	const shape = options?.shape ?? resolveShape(options?.model);
 	const frameSize = options?.frameSize ?? shape.frameSize;
 	const geo = geometry(shape, frameSize);
 	const normalized = normalize(text);
 	const frames: ImageContent[] = [];
-	for (let offset = 0; offset < normalized.length; offset += geo.capacity) {
-		if (options?.maxFrames !== undefined && frames.length >= options.maxFrames) break;
-		const rendered = render(normalized.slice(offset, offset + geo.capacity), shape, frameSize);
+	const push = (rendered: RenderedFrame): void => {
 		frames.push({
 			type: "image",
 			data: rendered.data,
 			mimeType: "image/png",
 			...(shape.imageDetail ? { detail: shape.imageDetail } : {}),
 		});
+	};
+	if (shape.columns === 2) {
+		const finish = pageFinisher(shape);
+		for (const page of docPages(normalized, geo)) {
+			if (options?.maxFrames !== undefined && frames.length >= options.maxFrames) break;
+			push(render(finish(page), shape, frameSize));
+		}
+		return frames;
+	}
+	for (let offset = 0; offset < normalized.length; offset += geo.capacity) {
+		if (options?.maxFrames !== undefined && frames.length >= options.maxFrames) break;
+		let chunk = normalized.slice(offset, offset + geo.capacity);
+		if (shape.stopwordDim) chunk = dimStopwords(chunk);
+		push(render(chunk, shape, frameSize));
 	}
 	return frames;
 }
 
-/** Frames needed to hold `text` at the given shape/size, without rendering. */
+/** Frames needed to hold `text` at the given shape/size, without rendering.
+ *  For doc shapes this wraps the text once and counts pages of `2 * rows`
+ *  lines; for grid shapes it divides by the frame capacity. */
 export function frames(text: string, options?: Pick<RenderManyOptions, "shape" | "model" | "frameSize">): number {
-	const shape = options?.shape ?? resolveShape(options?.model?.api);
+	const shape = options?.shape ?? resolveShape(options?.model);
 	const geo = geometry(shape, options?.frameSize ?? shape.frameSize);
-	return Math.ceil(normalize(text).length / geo.capacity);
+	const normalized = normalize(text);
+	if (shape.columns === 2) return Math.ceil(wrap(normalized, geo.cols).length / (2 * geo.rows));
+	return Math.ceil(normalized.length / geo.capacity);
 }
 
 // ============================================================================
@@ -639,6 +1062,7 @@ export function getPreservedArchive(preserveData: Record<string, unknown> | unde
 		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 } : {}),
 	};
 }
 
@@ -661,7 +1085,10 @@ export function images(archive: Archive): ImageContent[] {
  * 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. Pages past the frame budget are never rendered (providers with
+ * hard image caps silently drop excess frames on the wire) — the newest
+ * unrendered slice survives verbatim as a text tail on the summary and is
+ * folded back into frames by the next compaction.
  *
  * Frames archived under a different shape (provider switches, legacy 5x8
  * sessions) are kept as-is — each frame carries its own geometry, and the
@@ -679,7 +1106,7 @@ 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?.api);
+	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);
@@ -697,14 +1124,49 @@ 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));
+		}
+	}
+
+	// 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 newFrames: Frame[] = [];
-	let dimOpen = false;
-	for (let offset = 0; offset < archiveText.length; offset += geo.capacity) {
-		let chunk = archiveText.slice(offset, offset + geo.capacity);
-		// Re-open a dim span that the previous frame boundary cut through.
-		if (dimOpen) chunk = DIM_ON + chunk;
-		dimOpen = chunk.lastIndexOf(DIM_ON) > chunk.lastIndexOf(DIM_OFF);
-		const rendered = render(chunk, shape, frameSize);
+	const finish = pageFinisher(shape);
+	for (const page of renderPages) {
+		const rendered = render(finish(page), shape, frameSize);
 		newFrames.push({
 			data: rendered.data,
 			mimeType: "image/png",
@@ -714,31 +1176,39 @@ export async function compact<TMessage = Message>(
 			font: shape.font,
 			variant: shape.variant,
 			lineRepeat: shape.lineRepeat,
+			...(shape.columns === 2 ? { columns: 2 } : {}),
+			...(shape.stopwordDim ? { stopwordDim: true } : {}),
 			...(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;
+	// 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 frames = [...keptPrev, ...newFrames];
 	const totalChars = frames.reduce((sum, frame) => sum + frame.chars, 0);
 	const mixedShapes = frames.some(
 		frame =>
 			frame.cols !== geo.cols ||
 			frame.rows !== geo.rows ||
 			(frame.variant ?? "sent") !== shape.variant ||
-			(frame.lineRepeat ?? 1) !== shape.lineRepeat,
+			(frame.lineRepeat ?? 1) !== shape.lineRepeat ||
+			(frame.columns ?? 1) !== (shape.columns ?? 1) ||
+			(frame.stopwordDim ?? false) !== (shape.stopwordDim ?? false),
 	);
 
 	let summary: string;
@@ -753,11 +1223,14 @@ export async function compact<TMessage = Message>(
 			rows: geo.rows,
 			sentenceInk: shape.variant === "sent",
 			lineRepeated: shape.lineRepeat > 1,
+			docColumns: shape.columns === 2,
+			stopwordDimmed: shape.stopwordDim === true,
 			dimmedToolResults: options?.dimToolResults !== false,
 			mixedShapes,
 			totalChars,
 			truncatedChars,
 			includedPreviousSummary,
+			textTail: textTail.length > 0 ? toPlainText(textTail) : undefined,
 		});
 	}
 	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
@@ -766,11 +1239,12 @@ export async function compact<TMessage = Message>(
 	// 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 };
+	const archive: Archive = { frames, totalChars, truncatedChars, ...(textTail ? { textTail } : {}) };
 
+	const textTailNote = textTail ? ` (+${textTail.length.toLocaleString()} chars as text)` : "";
 	return {
 		summary,
-		shortSummary: `Archived ${totalChars.toLocaleString()} chars of history onto ${frames.length} snapcompact frame${frames.length === 1 ? "" : "s"}`,
+		shortSummary: `Archived ${totalChars.toLocaleString()} chars of history onto ${frames.length} snapcompact frame${frames.length === 1 ? "" : "s"}${textTailNote}`,
 		firstKeptEntryId,
 		tokensBefore,
 		details: { readFiles, modifiedFiles },