@linxiraos/pi-snapcompact 1.0.9 → 1.1.0

package/CHANGELOG.md

@@ -2,206 +2,11 @@
 
 ## [Unreleased]
 
-## [1.0.9] - 2026-08-19
-
-## [17.2.15] - 2026-08-12
-
-### Fixed
-
-- Fixed Anthropic model ID parsing to be case-insensitive and extended the high-resolution 1932px frame tier to Claude Opus 5 and later, preventing sessions from falling back to lower-resolution 1568px frames and preserving full history per compaction.
-
-## [17.1.5] - 2026-07-27
-
-### Fixed
-
-- Fixed snapcompact resume guides reporting only the HQ grid width for mixed-width foveated archives ([#6712](https://github.com/can1357/oh-my-pi/issues/6712)).
-
-## [17.1.0] - 2026-07-24
-
-### Added
-
-- Added an `includeThinking` serialization option (defaulting to `true`) to allow excluding assistant reasoning (`¶think:` sections) from archived transcripts.
-
-## [16.5.0] - 2026-07-13
-
-### Changed
-
-- Updated archived transcript rendering to use a more compact format with `¶user:`, `¶think:`, `¶ai:`, and `¶call:` scopes, omitting repeated adjacent scope headers and appending tool-call intents as comments.
-
-## [16.3.7] - 2026-07-05
-
-### Fixed
-
-- Fixed `resolveShapeForText(..., "auto")` to correctly select the `silver16-bw` shape for CJK-heavy transcript text while preserving explicit shape overrides.
-
-## [16.2.8] - 2026-06-30
-
-### Fixed
-
-- Fixed large snapcompact archives being reconstructed into unbounded per-request image payloads by adding a frame base64 byte budget and omitting over-budget archive frames from prompt blocks. ([#3792](https://github.com/can1357/oh-my-pi/issues/3792))
-
-## [16.2.7] - 2026-06-30
-
-### Added
-
-- Added the `silver16-bw` shape backed by an embedded Silver TrueType font to support CJK and other non-Latin text.
-- Added `resolveShapeForText` to support font-aware shape resolution.
-
-### Changed
-
-- Improved non-ASCII text normalization by folding semantic emojis to ASCII labels (e.g., `[OK]`, `[WARN]`), dropping decorative emojis, and folding box-drawing symbols to ASCII skeletons.
-- Enhanced missing glyph rendering to use the embedded Silver TrueType fallback per-character, including support for East Asian wide characters across two grid cells.
-- Updated text wrapping, pagination, and provider shape geometries to support wide character footprints and updated X.org 8x13 font metrics.
-
-## [16.1.23] - 2026-06-26
-
-### Added
-
-- Added `archiveSourceText(archive)` to extract a persisted frame archive's source text as plain text for LLM summarization. ([#3561](https://github.com/can1357/oh-my-pi/pull/3561) by [@serverinspector](https://github.com/serverinspector))
-- Added `stripPreservedArchive(preserveData)` to drop the persisted frame-archive slot (`PRESERVE_KEY`) and collapse to `undefined` when no other state remains — shared by the agent and coding-agent compaction paths instead of duplicating the strip rule.
-
-## [16.1.13] - 2026-06-22
-
-### Fixed
-
-- Fixed the Umans provider image budget to match its 10-image request cap.
-
-## [16.1.8] - 2026-06-20
-
-### Breaking Changes
-
-- Changed core rendering functions `render` and `renderMany` to be asynchronous
-
-## [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
+## [1.1.0] - 2026-08-25
 
 ### Changed
 
-- Refined elision markers for file operations and truncated text for better display consistency
-- Updated summary text for consistent descriptions of archived tool output
-- Folded a much wider range of Unicode to ASCII in `normalize()` before native rendering: added a per-character Unicode NFKD decomposition fallback (fullwidth forms, super/subscripts, ligatures, circled and math-styled alphanumerics, Roman numerals, vulgar fractions) and expanded the `CHAR_FOLD` punctuation table (more quotes/primes, hyphens, the fraction slash, dot leaders, bullets, and arrows) so undrawable glyphs land on close ASCII equivalents instead of `?`
-
-## [16.0.8] - 2026-06-18
-
-### Added
-
-- Added `<out>` block wrapping for tool results to improve document structure
-- Rendered thinking process as italicized blocks above assistant text
-- Displayed tool call intents as `//` comments in tool call headers
-- Changed conversation role markers to standard Markdown headings
-
-### Changed
-
-- Merged tool results into their corresponding tool call blocks
-- Preserved prose formatting around tool calls to maintain conversation flow
-- Hidden `_i` argument from tool call output when an intent is provided
-- Optimized assistant turn output to group thinking and text blocks efficiently
-
-### Fixed
-
-- Fixed improper splitting of assistant messages around useless tool calls
-
-## [16.0.1] - 2026-06-15
-
-### Added
-
-- Added `openai-codex` to first-party provider image budgets so ChatGPT Plus/Pro Codex sessions use the same 200-image request cap as OpenAI API sessions instead of the unknown-provider floor.
-
-## [15.13.1] - 2026-06-15
-
-### Added
-
-- Added two spacing-tuned frame variants to `SHAPE_VARIANTS`: `8on22-bw` (8x13 glyphs on a 22px pitch — extra line spacing) and `11on16-bw` (8x13 glyphs on an 11px advance — extra letter spacing). Both pin the indexed `stretch: false` path, so the native renderer draws natural-size glyphs on the padded cell box (the Rust path already advances by `cellWidth` and the new variants validate horizontal padding)
-
-### Changed
-
-- **Changed the per-provider default shapes to the spacing-tuned cells.** The previous shapes were tuned on the SQuAD *prose* eval, where dense cells won; a new tool-result legibility benchmark (`research/toolbench.py` — real `search`/`read`/`find` output with structure-sensitive QA) showed the prose-era density erases the line numbers and indentation that code/search output depends on. Anthropic moves from `6x12-dim` to `11on16-bw` (opus-4.8 f1 .806 vs .755 for plain `8on16-bw` and .351 for `6x12-dim`, which fell below the OCR ~16px/char floor and abstained); OpenAI and Google move to `8on22-bw` (gemini-3.5-flash f1 .934 vs .807 for `8on16-bw` and .287 for `doc-8on16-sent-dim`; same leading win on gpt-5.5/gpt-5.4-mini). Kimi and GLM keep their measured `8on16-bw`. The bigger cells pack fewer chars per frame, so inline frame-swapping now breaks even at a larger tool-result size
-
-## [15.12.1] - 2026-06-12
-
-### Changed
-
-- `serializeConversation` now skips tool call/result pairs whose result is flagged contextually useless (`useless: true`, non-error), so archived frames stop carrying zero-match searches and timed-out waits
-
-## [15.11.7] - 2026-06-12
-
-### Added
-
-- Added `SHAPE_VARIANTS`, the catalog of research-eval frame variants the native renderer reproduces faithfully (`8x8r`/`8x8u`/`6x6u`/`5x8` × `sent`/`bw`), with `ShapeVariantName`, `SHAPE_VARIANT_NAMES`, and the `isShapeVariantName` guard
-- `resolveShape(api, variant?)` now accepts an explicit variant name (or `"auto"`); forced variants keep their geometry but are re-priced for the target provider's image billing (token estimate and OpenAI `original` detail hint)
-- Added the six research-eval winning frame variants to `SHAPE_VARIANTS`: `6x12-dim` (Claude fable), `8x13-bw` (Opus), `8on16-bw` (GPT grid runner-up), `doc-8on16-bw` (GPT), `doc-8on16-sent` (GLM), and `doc-8on16-sent-dim` (Gemini/Kimi), backed by new `Shape` fields `stretch` (disable Lanczos stretch: natural glyphs on a larger cell pitch), `columns` (two word-wrapped newspaper columns), `stopwordDim`, and the X.org `6x12`/`8x13` fonts
-- Added `dimStopwords()`, which prints high-frequency function words in dim ink via zero-width markers (skipping spans that are already dim), and `wrap()`, the greedy word-wrap used to typeset doc-layout pages; `geometry`/`render`/`renderMany`/`frames`/`compact` understand doc shapes (wrap once, paginate into `2 * rows`-line pages), and compaction frames persist `columns`/`stopwordDim` for mixed-shape detection
-- `resolveShape` now takes a `ShapeTarget` (`{ api, id }` — a pi-ai `Model` works as-is) and detects the ideal shape from the **model id**, not just the wire API: a Claude routed through Vertex or an OpenAI-compatible gateway keeps its Claude shape, with billing still priced by the API family actually carrying the request. `idealShapeVariant(modelId)` exposes the model-line table; unmeasured models fall back to the API family's winner
-- `resolveShape` now also resolves an ideal **frame size** per model line, and billing estimates come from verified per-family formulas instead of flat 1568px constants: Anthropic bills 28px patches capped at 4,784 visual tokens (+5% margin), Gemini 3.x bills a fixed 1,120-token `media_resolution` budget per image at any pixel size, and OpenAI bills 32px patches × 1.2 under the 10,000-patch `detail: "original"` budget. High-res Claude lines (Opus 4.7+, Fable, Mythos — native 2576px-edge ingestion) get 1932px frames (same recall and cost, a third fewer frames); Gemini gets 2048px frames (+70% chars per frame at the same bill); GPT and Kimi stay at 1568px (area-proportional billing and a model-side 1792px processor cap, respectively). `idealShapeVariant` now returns an `IdealShape` (`{ variant, frameSize? }`)
-- Added per-provider image-count budgets: `PROVIDER_IMAGE_BUDGETS`, `DEFAULT_PROVIDER_IMAGE_BUDGET`, `providerImageBudget()`, and `providerFrameBudget()` (the image budget clamped to `MAX_FRAMES`). OpenRouter is capped at its measured hard limit of 8 images per request (excess images are silently dropped with no error); unknown providers get a safe floor of 5
-- Added `Archive.textTail`: archive content past the frame budget is no longer dropped — `compact()` stops rendering at the budget and keeps the newest unframed slice as verbatim text on the summary (capped at two frame capacities with middle elision, counted into `truncatedChars` when elided). The tail persists in `preserveData` and is folded back into frames by the next compaction
-
-### Changed
-
-- Frames are no longer padded to a square: the native renderer clips each PNG's height to the text rows actually printed, so a partially filled frame (typically the newest) bills only the pixel rows it uses
-- **Changed the OpenAI default shape from `6x6u-sent` to `8on16-bw`.** A production-regime mono eval (gpt-5.5, the full 800k-char SQuAD flow in one request, n=50) scored the old dense default f1 .602 vs .851 for `8on16-bw` rendered by the production pipeline, at near-equal total cost (the dense cells burned the frame savings on reasoning tokens); chunked exp14 had already scored `8on16-bw` .906. `SHAPES.openaiDense` is renamed to `SHAPES.openai`
-- **Changed the Google default shape from `8x8r-sent` to `doc-8on16-sent-dim`.** Production-rendered mono eval on gemini-3.5-flash (400k chars, one request, n=25): f1 .900 vs .853 for the repeated grid at lower cost, agreeing with the chunked round-2 winner
-- **Changed the Anthropic default shape from `8x8r-bw` to `6x12-dim`.** Production mono eval on claude-fable (400k chars, one request, n=25): f1 .840 vs .877 for the repeated grid — within noise — at 37% lower cost (12 frames instead of 21 per 400k chars), with clean completions in every probe; opus reads the same trade (.800 vs .833 at 42% lower cost)
-- `normalize()` now keeps line structure: whitespace runs containing a line break collapse to `NEWLINE_GLYPH` (U+2588 FULL BLOCK, drawn by the native renderer as a pitch-black cell one character wide) instead of a plain space; leading/trailing breaks are trimmed, and the frame-reading prompt explains the marker
-- `normalize()` now skips characters the fonts cannot render instead of printing `?` blanks: whole ANSI escape sequences are stripped, and bare control characters, zero-width format characters (ZWSP, BOM, directional marks), combining marks, and lone surrogates are dropped without occupying a cell; `?` remains the fallback for unsupported graphic characters only
-
-## [15.11.4] - 2026-06-12
-
-### Breaking Changes
-
-- Renamed every export to drop the `snapcompact`/`Snapcompact`/`SNAPCOMPACT_` qualifier — the package is meant to be consumed via `import * as snapcompact from "@linxiraos/pi-snapcompact"`. Functions: `snapcompactCompact` → `compact`, `renderSnapcompactFrame` → `render`, `snapcompactGeometry` → `geometry`, `normalizeForSnapcompact` → `normalize`, `serializeSnapcompactConversation` → `serializeConversation`, `snapcompactImages` → `images`, `getPreservedSnapcompactArchive` → `getPreservedArchive`, `isSnapcompactShape` → `isShape`, `resolveSnapcompactShape` → `resolveShape`, `createSnapcompactFileOps` → `createFileOps`, `computeSnapcompactFileLists` → `computeFileLists`, `upsertSnapcompactFileOperations` → `upsertFileOperations`. Types: `SnapcompactShape` → `Shape`, `SnapcompactFrame` → `Frame`, `SnapcompactArchive` → `Archive`, `SnapcompactGeometry` → `Geometry`, `SnapcompactOptions` → `Options`, `SnapcompactSerializeOptions` → `SerializeOptions`, `SnapcompactFileOperations` → `FileOperations`, `SnapcompactCompactionDetails`/`Preparation`/`Result` → `CompactionDetails`/`CompactionPreparation`/`CompactionResult`, `SnapcompactConvertToLlm` → `ConvertToLlm`. Constants: `SNAPCOMPACT_X` → `X` (`SHAPES`, `FRAME_SIZE`, `MAX_FRAMES`, `FRAME_TOKEN_ESTIMATE`, `PRESERVE_KEY`, `TOOL_RESULT_MAX_CHARS`, `TOOL_ARG_MAX_CHARS`, `TOOL_CALL_MAX_CHARS`, `TRUNCATE_HEAD_RATIO`, `DIM_ON`, `DIM_OFF`).
-
-### Added
-
-- Added `renderMany()` for paging arbitrary text into snapcompact PNG frames as LLM image blocks, and `frames()` for predicting the frame count without rendering
-
-## [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 `@linxiraos/pi-snapcompact` with typed access to snapcompact APIs
-- Published `@linxiraos/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
+- 同步上游 OMP v18.0.3 / v18.0.4（内部运行时与构建改进，无独立用户可见变更）。
 
 ## [1.0.0] - 2026-08-13
 

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,66 +1,65 @@
 {
-	"type": "module",
-	"name": "@linxiraos/pi-snapcompact",
-	"version": "1.0.9",
-	"description": "Bitmap-frame context compression for vision-capable LLMs",
-	"homepage": "https://linxira-os.github.io",
-	"author": "Can Boluk",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Linxira-OS/linxira-zeta.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": {
-		"@linxiraos/pi-ai": "1.0.9",
-		"@linxiraos/pi-catalog": "1.0.9",
-		"@linxiraos/pi-natives": "1.0.9",
-		"@linxiraos/pi-utils": "1.0.9",
-		"@linxiraos/pi-wire": "1.0.9"
-	},
-	"devDependencies": {
-		"@types/bun": "^1.3.14"
-	},
-	"engines": {
-		"bun": ">=1.3.14"
-	},
-	"files": [
-		"src",
-		"README.md",
-		"CHANGELOG.md",
-		"dist/types"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./src/index.ts"
-		},
-		"./snapcompact": {
-			"types": "./dist/types/snapcompact.d.ts",
-			"import": "./src/snapcompact.ts"
-		},
-		"./*": {
-			"types": "./dist/types/*.d.ts",
-			"import": "./src/*.ts"
-		}
-	}
-}
+  "type": "module",
+  "name": "@linxiraos/pi-snapcompact",
+  "version": "1.1.0",
+  "description": "Bitmap-frame context compression for vision-capable LLMs",
+  "homepage": "https://linxira-os.github.io/zeta/",
+  "author": "Can Boluk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+    "directory": "packages/snapcompact"
+  },
+  "bugs": {
+    "url": "https://github.com/Linxira-OS/linxira-zeta/issues"
+  },
+  "keywords": [
+    "context-compression",
+    "vision",
+    "compaction",
+    "llm"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.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": {
+    "@linxiraos/pi-ai": "catalog:",
+    "@linxiraos/pi-catalog": "catalog:",
+    "@linxiraos/pi-natives": "catalog:",
+    "@linxiraos/pi-utils": "catalog:",
+    "@linxiraos/pi-wire": "catalog:"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./snapcompact": {
+      "types": "./src/snapcompact.ts",
+      "import": "./src/snapcompact.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts"
+    }
+  }
+}

package/src/snapcompact.ts

@@ -519,6 +519,11 @@ export function providerImageBudget(provider: string | undefined): number {
 	return (provider !== undefined ? PROVIDER_IMAGE_BUDGETS[provider] : undefined) ?? DEFAULT_PROVIDER_IMAGE_BUDGET;
 }
 
+/** Archive frame cap for `provider`: image budget, never above {@link MAX_FRAMES_DEFAULT}. */
+export function providerFrameBudget(provider: string | undefined): number {
+	return Math.min(providerImageBudget(provider), MAX_FRAMES_DEFAULT);
+}
+
 /** Key under `CompactionEntry.preserveData` holding the frame archive. */
 export const PRESERVE_KEY = "snapcompact";
 
@@ -775,6 +780,132 @@ function truncateForSummary(text: string, maxChars: number, headRatio: number):
 	return `${text.slice(0, headChars)} […${elided}ch elided…] ${tail}`;
 }
 
+/** One elision marker as emitted by {@link truncateForSummary} (Unicode
+ *  ellipses) or as persisted after `normalize()` (ASCII dots). */
+const ELIDED_MARKER = String.raw`\[(?:…|\.{3})\d+ch elided(?:…|\.{3})\]`;
+
+/** Unquoted RFC 2045 token used as a media-type parameter name or value.
+ *  Quoted-string values (RFC 822) are out of scope. */
+const MEDIA_TYPE_TOKEN = String.raw`[\w!#$%&'*+.^|~-]+`;
+
+/** An inline base64 data URL. The payload may be empty or carry one embedded
+ *  elision marker so fragments left by pre-guard slices — including a cut
+ *  landing exactly on `;base64,` — still match. RFC 2397 allows `*( ";" parameter )`
+ *  between type/subtype and the terminal `;base64`; unquoted tokens are matched,
+ *  quoted-string values are out of scope. `data:` and `base64` match
+ *  case-insensitively (`gi`). Matching starts at `data:`; Markdown wrappers are
+ *  recovered by {@link adjacentMarkdownOpenerStart} after each hit. */
+const DATA_URL_ATOM = new RegExp(
+	String.raw`data:([A-Za-z][\w.+-]*\/[\w.+-]+(?:;${MEDIA_TYPE_TOKEN}=${MEDIA_TYPE_TOKEN})*);base64,` +
+		String.raw`([A-Za-z0-9+/=]*(?:\s*${ELIDED_MARKER}\s*[A-Za-z0-9+/=]*)?)` +
+		String.raw`(\s*\))?`,
+	"gi",
+);
+
+const ELIDED_MARKER_RE = new RegExp(String.raw`\s*${ELIDED_MARKER}\s*`);
+const MARKDOWN_WHITESPACE_CHAR = /\s/;
+
+/** Canonical base64: 4-char groups with valid terminal padding. */
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)$/;
+
+/** A non-canonical payload at least this long is a damaged fragment of a real
+ *  data URL (e.g. an archive head cut mid-payload by a structure-blind slice),
+ *  not a prose mention like `data:image/png;base64,abc`. */
+const DAMAGED_PAYLOAD_MIN_CHARS = 40;
+
+/** Context for {@link elideDataUrls}. `source` text is intact (never sliced),
+ *  so a short non-canonical payload is a prose mention and stays untouched.
+ *  `archive` text may have been cut by pre-guard structure-blind slices at
+ *  any offset — even 0–39 chars past `;base64,` — so every recognized prefix
+ *  is suspect and is always elided. */
+type DataUrlContext = "source" | "archive";
+
+/** Start of `!?[label](\s*` immediately before `dataIndex`, or `undefined`.
+ *  The opener must lie in `[cursor, dataIndex)`. Nested `[` in the label is
+ *  kept (the old `[^\]\n]*` class allowed it) by taking the earliest `[` after
+ *  a prior `]`, newline, or `cursor`; the scan never walks already-emitted
+ *  text, so repeated `](data:...)` stays linear. */
+function adjacentMarkdownOpenerStart(text: string, dataIndex: number, cursor: number): number | undefined {
+	let i = dataIndex;
+	while (i > cursor && MARKDOWN_WHITESPACE_CHAR.test(text.charAt(i - 1))) i--;
+	// `](` and any following whitespace must sit in [cursor, dataIndex).
+	if (i - 2 < cursor || text.charAt(i - 1) !== "(" || text.charAt(i - 2) !== "]") return undefined;
+	let opener = -1;
+	for (let j = i - 3; j >= cursor; j--) {
+		const c = text.charAt(j);
+		if (c === "]" || c === "\n") break;
+		if (c === "[") opener = j;
+	}
+	if (opener < 0) return undefined;
+	return opener > cursor && text.charAt(opener - 1) === "!" ? opener - 1 : opener;
+}
+
+/** Replace every inline base64 data URL atomically with a deterministic
+ *  placeholder. A character cap that slices inside a base64 payload leaves a
+ *  recognizable image reference that can never decode; OpenAI-dialect
+ *  providers reject such requests as invalid image input, and because the
+ *  corrupted text persists in the archive the session re-fails on every later
+ *  request. The payload is worthless to a model as text, so the whole atom —
+ *  Markdown wrapper included — collapses to its metadata. Payloads already
+ *  carrying an elision marker, and non-canonical fragments left by pre-guard
+ *  slices, are healed the same way.
+ *
+ *  The placeholder's `<mime>` is the media type as written: type/subtype plus
+ *  any unquoted RFC 2397 `;parameter=value` segments, original case preserved.
+ *  Parameters are kept rather than stripped to a bare type/subtype so charset
+ *  (and similar) remain visible after elision and the label stays a pure
+ *  function of the captured text. */
+function elideDataUrls(text: string, context: DataUrlContext = "source"): string {
+	if (!/;base64,/i.test(text)) return text;
+	DATA_URL_ATOM.lastIndex = 0;
+	let match = DATA_URL_ATOM.exec(text);
+	if (match === null) return text;
+	const out: string[] = [];
+	let cursor = 0;
+	while (match !== null) {
+		const urlStart = match.index;
+		const urlEnd = urlStart + match[0].length;
+		const mime = match[1] ?? "";
+		const payload = match[2] ?? "";
+		const closer = match[3];
+		const marker = ELIDED_MARKER_RE.exec(payload);
+		const isAtom =
+			context === "archive" ||
+			marker !== null ||
+			CANONICAL_BASE64.test(payload) ||
+			payload.length >= DAMAGED_PAYLOAD_MIN_CHARS;
+		if (!isAtom) {
+			// Advance through short prose too, so a later wrapper cannot swallow
+			// a data URL already copied out of its Markdown label.
+			out.push(text.slice(cursor, urlEnd));
+			cursor = urlEnd;
+		} else {
+			const b64Chars = marker
+				? payload.length - marker[0].length + Number(/\d+/.exec(marker[0])?.[0] ?? 0)
+				: payload.length;
+			const placeholder = `[data URL omitted: ${mime}, ${b64Chars} base64 chars]`;
+			const foundOpener = adjacentMarkdownOpenerStart(text, urlStart, cursor);
+			const openerStart = foundOpener !== undefined && foundOpener >= cursor ? foundOpener : undefined;
+			const emitStart = openerStart ?? urlStart;
+			out.push(text.slice(cursor, emitStart));
+			// Swallow the Markdown wrapper only when both delimiters matched;
+			// otherwise re-emit whichever half was captured untouched. An opener
+			// that starts before the already-emitted cursor would overlap a prior
+			// replacement, so that URL is treated as bare.
+			if (openerStart !== undefined && closer !== undefined) {
+				out.push(placeholder);
+			} else {
+				const opener = openerStart !== undefined ? text.slice(openerStart, urlStart) : "";
+				out.push(opener, placeholder, closer ?? "");
+			}
+			cursor = urlEnd;
+		}
+		match = DATA_URL_ATOM.exec(text);
+	}
+	out.push(text.slice(cursor));
+	return out.join("");
+}
+
 const DIM_MARKERS = /[\u000e\u000f]/g;
 
 /** Plain-text history kept verbatim at each chronological edge, in HQ-frame-
@@ -836,7 +967,7 @@ export function serializeConversation(messages: Message[], options?: SerializeOp
 	// Wrap a raw tool-result body in an `<out>` block, dimming only the body so
 	// the frame coloring keeps scope markers and calls loud.
 	const renderResultBlock = (rawText: string): string => {
-		const body = truncateForSummary(stripDimMarkers(rawText), toolResultMaxChars, headRatio);
+		const body = truncateForSummary(elideDataUrls(stripDimMarkers(rawText)), toolResultMaxChars, headRatio);
 		return `<out>\n${dimToolResults ? `${DIM_ON}${body}${DIM_OFF}` : body}\n</out>`;
 	};
 
@@ -894,7 +1025,7 @@ export function serializeConversation(messages: Message[], options?: SerializeOp
 							.filter(([key]) => key !== INTENT_FIELD)
 							.map(
 								([key, value]) =>
-									`${key}=${truncateForSummary(JSON.stringify(value) ?? "undefined", toolArgMaxChars, headRatio)}`,
+									`${key}=${truncateForSummary(elideDataUrls(JSON.stringify(value) ?? "undefined"), toolArgMaxChars, headRatio)}`,
 							)
 							.join(", "),
 						toolCallMaxChars,
@@ -1616,7 +1747,7 @@ export function archiveSourceText(archive: Archive): string | undefined {
 		[archive.textHead, archive.textTail]
 			.filter((part): part is string => typeof part === "string" && part.length > 0)
 			.join(NEWLINE_GLYPH);
-	return text.length > 0 ? toPlainText(text) : undefined;
+	return text.length > 0 ? elideDataUrls(toPlainText(text), "archive") : undefined;
 }
 
 /** Build the text used to choose and preflight a font-aware snapcompact shape. */
@@ -1704,7 +1835,7 @@ export function historyBlocks(archive: Archive, options: HistoryBlockOptions = {
 			: hasOmittedImages
 				? `\n${omittedFrameNotice(budgeted.omittedFrames, budgeted.omittedBytes)}\n`
 				: "";
-		blocks.push({ type: "text", text: toPlainText(archive.textHead) + suffix });
+		blocks.push({ type: "text", text: elideDataUrls(toPlainText(archive.textHead), "archive") + suffix });
 	} else if (hasOmittedImages && !hasImages) {
 		blocks.push({ type: "text", text: omittedFrameNotice(budgeted.omittedFrames, budgeted.omittedBytes) });
 	}
@@ -1721,7 +1852,7 @@ export function historyBlocks(archive: Archive, options: HistoryBlockOptions = {
 			: archive.truncatedChars > 0 || hasOmittedImages
 				? "\n-------------- middle history omitted above\n"
 				: "";
-		const tail = prefix + toPlainText(archive.textTail);
+		const tail = prefix + elideDataUrls(toPlainText(archive.textTail), "archive");
 		const lastBlock = blocks[blocks.length - 1];
 		if (lastBlock?.type === "text") {
 			lastBlock.text += tail;
@@ -1917,11 +2048,14 @@ export async function compact<TMessage = Message>(
 			.join(NEWLINE_GLYPH);
 	// Legacy archives may carry `¶think:` sections from before includeThinking
 	// existed; scrub them when this compaction excludes thinking so the
-	// re-rendered archive stops replaying reasoning (issue #6093).
+	// re-rendered archive stops replaying reasoning (issue #6093). They may
+	// also carry data URLs a pre-guard slice cut at any offset; heal those in
+	// archive context before the text is folded into the new source.
+	const previousTextHealed = elideDataUrls(previousTextRaw, "archive");
 	const previousText =
-		options?.includeThinking === false && previousTextRaw.length > 0
-			? stripThinkingSections(previousTextRaw)
-			: previousTextRaw;
+		options?.includeThinking === false && previousTextHealed.length > 0
+			? stripThinkingSections(previousTextHealed)
+			: previousTextHealed;
 	const hasPreviousText = previousText.length > 0;
 	const includedPreviousSummary = !hasPreviousText && !!previousSummary;
 	const shapeProbeText = renderabilityProbeText(serialized, previousPreserveData, previousSummary);
@@ -1949,6 +2083,12 @@ export async function compact<TMessage = Message>(
 	if (hasPreviousText) {
 		archiveText = archiveText.length > 0 ? `${previousText}${NEWLINE_GLYPH}${archiveText}` : previousText;
 	}
+	// Data URLs must never reach planArchive: its edge slices are structure-
+	// blind, and a split payload replays as broken image input on every later
+	// request. previousText is already strictly healed above; this source-mode
+	// pass covers intact URLs in fresh user/assistant text, which the
+	// serializer never truncates.
+	archiveText = elideDataUrls(archiveText);
 
 	const layout = planArchive(archiveText, high, low, maxFrames);
 	truncatedChars += layout.truncatedChars;

package/dist/types/index.d.ts

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

package/dist/types/snapcompact.d.ts

@@ -1,592 +0,0 @@
-/**
- * Snapcompact compaction: archive conversation history as dense bitmap images.
- *
- * Instead of asking an LLM to summarize discarded history, the serialized
- * conversation is rendered into PNG frames of pixel-font text that vision
- * models read back directly, like an archivist at a snapcompact frame
- * reader. Frames are `frameSize` wide; their height hugs the text rows
- * actually printed, so a partially filled frame never bills blank rows.
- *
- * The frame shape is provider-aware. Original choices came from the SQuAD
- * prose evals (`packages/snapcompact`, 200k-token monolithic runs); the
- * spacing choices below come from the tool-result legibility bench
- * (`research/toolbench.py`, real search/read/find output with structure QA),
- * which exposed that the prose-tuned dense cells erase the line numbers and
- * indentation that code/search output depends on:
- *
- * - **Anthropic** (`11on16-bw`): 8x13 glyphs on an 11px advance (extra
- *   letter-spacing), black ink. On the tool-result bench, tracking the
- *   readable cell beat plain `8on16-bw` (opus-4.8 f1 .806 vs .755) and far
- *   beat the prior dense `6x12-dim` (.351, which fell below the OCR ~16px/char
- *   floor and abstained). Opus 4.7+/Fable/Mythos ingest high-res natively
- *   (2576px edge, 4,784 visual-token cap), so those lines get 1932px frames:
- *   same bill, fewer frames. Older Claude lines downscale past 1568px.
- * - **Google** (`8on22-bw` @2048): 8x13 glyphs on a 22px pitch (extra line
- *   spacing), black ink. Leading lifted gemini-3.5-flash to f1 .934 vs .807
- *   for `8on16-bw` and .287 for the prior `doc-8on16-sent-dim`. Gemini 3.x
- *   bills a fixed `media_resolution` budget per image (default 1,120 tokens)
- *   regardless of pixels, so the 2048px frame carries more chars at the same
- *   bill.
- * - **OpenAI** (`8on22-bw`): same leading win (gpt-5.5/gpt-5.4-mini). Patch
- *   billing (32px × 1.2, 10k-patch budget at `detail: "original"`) is
- *   area-proportional, so resolution cannot improve chars/$ — 1568 stays.
- *   `detail: "high"` would downgrade (2,500-patch cap); `original` is sent.
- * - **Unknown providers** default to `8on22-bw` with Anthropic-style
- *   visual-token area billing. `providerImageBudget` still caps per-request
- *   images per provider so inline imaging cannot flood a request with
- *   attachments, but the old OpenRouter-specific 8-image cap is gone; routers
- *   now use the same permissive budget as direct Anthropic/Claude lines unless
- *   configured otherwise upstream.
- *
- * The whole pass is local and deterministic — no LLM call, no API key, no
- * latency beyond rendering. Rasterization and PNG encoding happen in native
- * code (`renderSnapcompactPng` in `crates/pi-natives/src/snapcompact.rs`).
- * Frames persist in the compaction entry's `preserveData` and are
- * re-attached to the compaction summary message on every context rebuild.
- */
-import type { Api, ImageContent, Message, TextContent } from "@linxiraos/pi-ai";
-/** One eval-validated frame shape: font, cell, ink, repetition, and size. */
-export interface Shape {
-    /** Bundled font in the native renderer. */
-    font: "5x8" | "8x8" | "6x12" | "8x13" | "silver";
-    /** Target cell advance in pixels; differing from the font's natural cell
-     *  renders via Lanczos stretch (anti-aliased RGB frame). */
-    cellWidth: number;
-    /** Target cell pitch in pixels. */
-    cellHeight: number;
-    /** `false` → glyphs drawn at natural size on the cell pitch (8on16);
-     *  `true`/`undefined` → legacy auto Lanczos stretch when cell ≠ natural. */
-    stretch?: boolean;
-    /** Ink: `sent` cycles six hues at sentence boundaries; `bw` is black. */
-    variant: "sent" | "bw";
-    /** Print stopwords in dim ink (research `dim`/`sent-dim` variants). */
-    stopwordDim?: boolean;
-    /** 1/undefined = row-major grid; 2 = two word-wrapped newspaper columns
-     *  (research `doc`). */
-    columns?: number;
-    /** Each text line is printed this many times; copies after the first sit
-     *  on a pale highlight band (redundancy coding). */
-    lineRepeat: number;
-    /** Frame edge in pixels. */
-    frameSize: number;
-    /** Per-frame billed-token estimate for the shape's target provider. */
-    frameTokenEstimate: number;
-    /** Resolution hint attached to frame images (OpenAI-only). */
-    imageDetail?: ImageContent["detail"];
-}
-/** Geometry half of a {@link Shape}: everything except provider billing. */
-export type ShapeGeometry = Omit<Shape, "frameTokenEstimate" | "imageDetail">;
-/**
- * Frame variants exercised by the SQuAD evals in `research/` that the native
- * renderer reproduces faithfully, keyed by their research names. Font codes:
- * `8x8u` unscii square cell, `8x8r` unscii with every line printed twice
- * (redundancy coding), `6x6u` unscii Lanczos-squeezed to 6x6 (densest
- * readable cell), `5x8` the X.org legacy font on its 2576px frame, `6x12`
- * and `8x13` the X.org misc fonts, `8on16` 8x13 glyphs on an 8x16 cell pitch
- * (no stretch, extra leading), `8on22` the same glyphs on a 22px pitch (more
- * leading), `11on16` the same glyphs on an 11px advance (more tracking),
- * `silver16` the embedded Silver TrueType font on a 16px grid for CJK and
- * other non-Latin text, and `doc-` prefixed shapes a two-column word-wrapped
- * newspaper layout. Ink: `sent` cycles six hues at sentence boundaries, `bw`
- * is plain black, `-dim` suffix prints stopwords in gray.
- */
-export declare const SHAPE_VARIANTS: {
-    readonly "8x8r-bw": {
-        readonly font: "8x8";
-        readonly cellWidth: 8;
-        readonly cellHeight: 8;
-        readonly variant: "bw";
-        readonly lineRepeat: 2;
-        readonly frameSize: 1568;
-    };
-    readonly "8x8r-sent": {
-        readonly font: "8x8";
-        readonly cellWidth: 8;
-        readonly cellHeight: 8;
-        readonly variant: "sent";
-        readonly lineRepeat: 2;
-        readonly frameSize: 1568;
-    };
-    readonly "8x8u-bw": {
-        readonly font: "8x8";
-        readonly cellWidth: 8;
-        readonly cellHeight: 8;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "8x8u-sent": {
-        readonly font: "8x8";
-        readonly cellWidth: 8;
-        readonly cellHeight: 8;
-        readonly variant: "sent";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "6x6u-bw": {
-        readonly font: "8x8";
-        readonly cellWidth: 6;
-        readonly cellHeight: 6;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "6x6u-sent": {
-        readonly font: "8x8";
-        readonly cellWidth: 6;
-        readonly cellHeight: 6;
-        readonly variant: "sent";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "5x8-bw": {
-        readonly font: "5x8";
-        readonly cellWidth: 5;
-        readonly cellHeight: 8;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 2576;
-    };
-    readonly "5x8-sent": {
-        readonly font: "5x8";
-        readonly cellWidth: 5;
-        readonly cellHeight: 8;
-        readonly variant: "sent";
-        readonly lineRepeat: 1;
-        readonly frameSize: 2576;
-    };
-    readonly "6x12-dim": {
-        readonly font: "6x12";
-        readonly cellWidth: 6;
-        readonly cellHeight: 12;
-        readonly variant: "bw";
-        readonly stopwordDim: true;
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "8x13-bw": {
-        readonly font: "8x13";
-        readonly cellWidth: 8;
-        readonly cellHeight: 13;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "8on16-bw": {
-        readonly font: "8x13";
-        readonly cellWidth: 8;
-        readonly cellHeight: 16;
-        readonly stretch: false;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "8on22-bw": {
-        readonly font: "8x13";
-        readonly cellWidth: 8;
-        readonly cellHeight: 22;
-        readonly stretch: false;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "11on16-bw": {
-        readonly font: "8x13";
-        readonly cellWidth: 11;
-        readonly cellHeight: 16;
-        readonly stretch: false;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "silver16-bw": {
-        readonly font: "silver";
-        readonly cellWidth: 16;
-        readonly cellHeight: 16;
-        readonly variant: "bw";
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "doc-8on16-bw": {
-        readonly font: "8x13";
-        readonly cellWidth: 8;
-        readonly cellHeight: 16;
-        readonly stretch: false;
-        readonly variant: "bw";
-        readonly columns: 2;
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "doc-8on16-sent": {
-        readonly font: "8x13";
-        readonly cellWidth: 8;
-        readonly cellHeight: 16;
-        readonly stretch: false;
-        readonly variant: "sent";
-        readonly columns: 2;
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-    readonly "doc-8on16-sent-dim": {
-        readonly font: "8x13";
-        readonly cellWidth: 8;
-        readonly cellHeight: 16;
-        readonly stretch: false;
-        readonly variant: "sent";
-        readonly stopwordDim: true;
-        readonly columns: 2;
-        readonly lineRepeat: 1;
-        readonly frameSize: 1568;
-    };
-};
-/** Research name of one renderable frame variant. */
-export type ShapeVariantName = keyof typeof SHAPE_VARIANTS;
-/** All variant names, in declaration order (for settings enums). */
-export declare const SHAPE_VARIANT_NAMES: readonly ShapeVariantName[];
-/** Runtime guard for variant names loaded from config. */
-export declare function isShapeVariantName(value: unknown): value is ShapeVariantName;
-/** Eval-validated shapes, keyed by the provider family they won on. */
-export declare const SHAPES: {
-    /** `11on16-bw`: 8x13 glyphs on an 11px advance (extra tracking), black ink.
-     *  Tool-result legibility bench (real search/read/find output, structure QA)
-     *  on opus-4.8: f1 .806 vs .755 for plain `8on16-bw` and .351 for the prior
-     *  `6x12-dim` default — letter-spacing the readable cell wins; the dense
-     *  6x12 was below the OCR ~16px/char floor and abstained. */
-    anthropic: Shape;
-    /** `8on22-bw`: 8x13 glyphs on a 22px pitch (extra leading), black ink.
-     *  Tool-result legibility bench on gemini-3.5-flash: f1 .934 vs .807 for
-     *  plain `8on16-bw` and .287 for the prior `doc-8on16-sent-dim`; the
-     *  line-spacing reduces row crowding so line numbers stay legible. */
-    google: Shape;
-    /** `8on22-bw`: 8x13 glyphs on a 22px pitch (extra leading), black ink.
-     *  Same line-spacing win for OpenAI; bench on gpt-5.5/gpt-5.4-mini showed
-     *  leading lifts recall on the readable cell over plain `8on16-bw`. */
-    openai: Shape;
-    /** Original 5x8 X.org shape (pre-shape-table sessions rendered this). */
-    legacy: Shape;
-};
-/** Runtime guard for shape overrides loaded from config or preserve data. */
-export declare function isShape(value: unknown): value is Shape;
-/** One model line's ideal format: variant plus an optional frame-size
- *  override when the line reads larger frames at no extra cost. */
-export interface IdealShape {
-    variant: ShapeVariantName;
-    frameSize?: number;
-}
-/** Eval-ideal format for a model id, or undefined when unmeasured. */
-export declare function idealShapeVariant(modelId: string): IdealShape | undefined;
-/** What will read the frames: the wire API (billing) and model id (shape). */
-export interface ShapeTarget {
-    api?: Api;
-    id?: string;
-}
-/**
- * Pick the frame shape for a reader. An explicit `variant` (anything but
- * `"auto"`) forces that geometry; otherwise the model id selects the
- * eval-winning shape — and frame size — for its model line, falling back to
- * the API family's winner when the model is unmeasured. Billing (token
- * estimate, detail hint) always follows the API family actually carrying
- * the request, computed for the resolved frame size. Accepts a full pi-ai
- * `Model` or any `{ api, id }` subset.
- */
-export declare function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape;
-/**
- * Pick the frame shape for `text`. Explicit variants remain forced. Auto first
- * resolves the model/provider default, then selects the Silver CJK grid when
- * the default font cannot safely render the text or wide CJK glyphs dominate
- * the transcript and Silver can render it safely.
- */
-export declare function resolveShapeForText(text: string, model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape;
-/** Legacy frame edge in pixels (the 5x8 shape's eval-validated size). New
- *  shapes carry their own `frameSize`. */
-export declare const FRAME_SIZE = 2576;
-/** Default upper bound on archive frames carried per compaction. Sized to hold
- *  ~400k tokens of the high-res Anthropic frame Opus reads (1932px ≈ 5,000
- *  billed tokens each → 80 frames) while staying under the ~100-image
- *  per-request wire cap. Oldest frames are dropped first once the budget is
- *  exceeded (mirrors how iterative text summaries fade the oldest detail); a
- *  caller may pass a lower `maxFrames` upper limit, and per-model context
- *  fitting is handled by the caller's overflow guard. */
-export declare const MAX_FRAMES_DEFAULT = 80;
-/** High-quality (legible) frames rendered at each chronological edge of a
- *  foveated archive — the session head (oldest) and the slice just before the
- *  text region (newest) — with the denser low-quality tier filling the middle. */
-export declare const HQ_EDGE_FRAMES = 3;
-/** Conservative per-frame token estimate used for context budgeting — the
- *  upper bound across shapes: high-res Claude frames hit the 4,784 visual-token
- *  cap, billed at +5% margin (ceil(4784 * 1.05)). Keeps the overflow guard from
- *  undercounting a high-res archive at the raised {@link MAX_FRAMES_DEFAULT}. */
-export declare const FRAME_TOKEN_ESTIMATE = 5024;
-/** Conservative upper bound for one persisted frame's base64 payload. The
- *  measured high-res Anthropic `8x13`/`11on16` PNG frames sit around 159 KB;
- *  170 KB leaves margin for denser glyph pages without permitting multi-MB
- *  standing request bodies at large context windows. */
-export declare const FRAME_DATA_BYTES_ESTIMATE = 170000;
-/** Maximum snapcompact image base64 carried in every rebuilt provider request.
- *  Above this, provider backends can accept the HTTP body but fail mid-stream
- *  with opaque 5xx errors. Keep this independent from visual-token budgeting:
- *  a 1M-token model can afford 70 images on paper, but not the resulting
- *  ~11 MB JSON payload on every turn. */
-export declare const FRAME_DATA_BYTES_BUDGET = 3000000;
-/** Frame-count cap implied by {@link FRAME_DATA_BYTES_BUDGET}. */
-export declare function maxFramesForDataBudget(maxFrameDataBytes?: number): number;
-/** Base64 byte length for persisted snapcompact frames. */
-export declare function frameDataBytes(frames: readonly Pick<Frame, "data">[]): number;
-/**
- * Per-request image-count budgets by provider id. These cap how many images an
- * entire request may carry (archive/system-prompt/tool-result imaging combined).
- * The values are conservative policy caps under the vendor hard limits
- * (Anthropic 100, OpenAI 500, Gemini ~2500); unknown providers fall to a safe
- * floor rather than sending unbounded attachments.
- */
-export declare const PROVIDER_IMAGE_BUDGETS: Record<string, number>;
-/** Safe floor for unknown providers (strictest mainstream measured: Groq ~5). */
-export declare const DEFAULT_PROVIDER_IMAGE_BUDGET = 5;
-/** Per-request image budget for `provider`; unknown providers get the floor. */
-export declare function providerImageBudget(provider: string | undefined): number;
-/** Key under `CompactionEntry.preserveData` holding the frame archive. */
-export declare const PRESERVE_KEY = "snapcompact";
-/** One developed snapcompact frame: a base64 PNG plus its reading geometry. */
-export interface Frame {
-    /** Base64-encoded PNG. */
-    data: string;
-    mimeType: string;
-    /** Characters per row in the frame grid (per-column width on doc frames). */
-    cols: number;
-    /** Text rows in the frame grid (unique lines, not repeated copies). */
-    rows: number;
-    /** Characters actually printed onto this frame. */
-    chars: number;
-    /** Shape metadata (absent on legacy frames, which are 5x8 `sent`). */
-    font?: Shape["font"];
-    variant?: Shape["variant"];
-    lineRepeat?: number;
-    /** 2 on two-column doc frames; absent on row-major grid frames. */
-    columns?: number;
-    /** True when stopwords were printed in dim ink. */
-    stopwordDim?: boolean;
-    /** Resolution hint forwarded to the provider when re-attaching. */
-    detail?: ImageContent["detail"];
-}
-/** Frame archive persisted under `preserveData[PRESERVE_KEY]`. */
-export interface Archive {
-    /** Rendered frames ordered oldest to newest, re-derived from {@link text}
-     *  each compaction with foveated quality tiers (HQ/LQ/HQ inside the imaged
-     *  middle). May be empty when the whole archive fits in text. */
-    frames: Frame[];
-    /** Characters currently readable across all frames plus the text regions. */
-    totalChars: number;
-    /** Characters dropped so far to respect the archive budget. */
-    truncatedChars: number;
-    /** Full kept archive source (oldest to newest, normalized, bounded to the
-     *  rendered budget) — the single source re-rendered each compaction. */
-    text?: string;
-    /** Oldest text region kept verbatim around the imaged middle. */
-    textHead?: string;
-    /** Newest text region kept verbatim around the imaged middle. */
-    textTail?: string;
-}
-export interface Geometry {
-    /** Characters per row (per-column line width when `columns === 2`). */
-    cols: number;
-    rows: number;
-    /** Characters that fit one frame (nominal upper bound on doc shapes,
-     *  where real consumption is wrap-dependent). */
-    capacity: number;
-}
-export interface Options<TMessage = Message> extends SerializeOptions {
-    /** App-level message transformer (same contract as agent-core's `SummaryOptions.convertToLlm`). */
-    convertToLlm?: ConvertToLlm<TMessage>;
-    /** Model whose provider API and id select the frame shape. */
-    model?: ShapeTarget;
-    /** Explicit shape override; wins over `model`. */
-    shape?: Shape;
-    /** Frame edge in pixels. Defaults to the shape's `frameSize`. */
-    frameSize?: number;
-    /** Upper limit on archive frames; clamped to (and defaulting to) {@link MAX_FRAMES_DEFAULT}. */
-    maxFrames?: number;
-}
-/** Result of rendering one frame. */
-export interface RenderedFrame {
-    /** Base64-encoded PNG, as returned by the native renderer. */
-    data: string;
-    cols: number;
-    rows: number;
-    /** Characters printed (ink toggles excluded; input may be shorter than capacity). */
-    chars: number;
-}
-export interface FileOperations {
-    read: Set<string>;
-    written: Set<string>;
-    edited: Set<string>;
-}
-export interface CompactionDetails {
-    readFiles: string[];
-    modifiedFiles: string[];
-}
-export interface CompactionPreparation<TMessage = Message> {
-    /** UUID of first entry to keep. */
-    firstKeptEntryId: string;
-    /** Messages that will be archived and discarded. */
-    messagesToSummarize: TMessage[];
-    /** Messages that will be archived as the split-turn prefix, if any. */
-    turnPrefixMessages: TMessage[];
-    tokensBefore: number;
-    /** Summary from previous compaction, for continuity when no prior snapcompact archive exists. */
-    previousSummary?: string;
-    /** Preserved opaque compaction payload from the previous compaction, if any. */
-    previousPreserveData?: Record<string, unknown>;
-    /** File operations extracted by the host agent. */
-    fileOps: FileOperations;
-}
-export interface CompactionResult<T = CompactionDetails> {
-    summary: string;
-    shortSummary?: string;
-    firstKeptEntryId: string;
-    tokensBefore: number;
-    details?: T;
-    preserveData?: Record<string, unknown>;
-}
-export type ConvertToLlm<TMessage = Message> = (messages: TMessage[]) => Message[];
-export declare function createFileOps(): FileOperations;
-export declare function isUrlSchemePath(path: string): boolean;
-export declare function computeFileLists(fileOps: FileOperations): CompactionDetails;
-export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
-/** Default per-tool-result character cap in serialized history. */
-export declare const TOOL_RESULT_MAX_CHARS = 2000;
-/** Default per-argument-value character cap inside serialized tool calls
- *  (write/edit bodies otherwise dump whole files into the archive). */
-export declare const TOOL_ARG_MAX_CHARS = 500;
-/** Default character cap across one tool call's full serialized argument list. */
-export declare const TOOL_CALL_MAX_CHARS = 2000;
-/** Default fraction of a truncation budget spent on the head; the remainder
- *  keeps the tail, where command errors and test failures usually land. */
-export declare const TRUNCATE_HEAD_RATIO = 0.6;
-/** Zero-width ink toggles understood by the native renderer (shift-out/in):
- *  text between them prints in dim gray ink without occupying a cell. */
-export declare const DIM_ON = "\u000E";
-export declare const DIM_OFF = "\u000F";
-/** Character budgets applied while serializing discarded history for frame
- *  rendering. Pass `Infinity` to disable an individual cap. */
-export interface SerializeOptions {
-    /** Per-tool-result cap. Defaults to {@link TOOL_RESULT_MAX_CHARS}. */
-    toolResultMaxChars?: number;
-    /** Per-argument-value cap. Defaults to {@link TOOL_ARG_MAX_CHARS}. */
-    toolArgMaxChars?: number;
-    /** Whole-argument-list cap per call. Defaults to {@link TOOL_CALL_MAX_CHARS}. */
-    toolCallMaxChars?: number;
-    /** Head share of each budget, clamped to [0, 1]. Defaults to {@link TRUNCATE_HEAD_RATIO}. */
-    truncateHeadRatio?: number;
-    /** Print tool-result text in dim gray ink so archived conversation reads
-     *  louder than archived tool noise. Defaults to `true`. */
-    dimToolResults?: boolean;
-    /** Serialize assistant reasoning as `¶think:` sections. Defaults to `true`.
-     *  Callers archiving for a Claude/Anthropic-dialect model set this `false`:
-     *  the archive frames are replayed as text into every later request, and
-     *  reasoning rendered back to Claude trips its `reasoning_extraction`
-     *  classifier (issue #6093). */
-    includeThinking?: boolean;
-}
-export declare function serializeConversation(messages: Message[], options?: SerializeOptions): string;
-/** Printed in place of newline runs: the native renderer fills this cell
- *  entirely with pitch-black ink, so line structure survives whitespace
- *  collapsing at a one-cell cost. */
-export declare const NEWLINE_GLYPH = "\u2588";
-export interface NormalizeOptions {
-    /** Shape whose font is tried before the embedded Silver fallback. */
-    shape?: Pick<Shape, "font">;
-    /** Native font name when a full shape is not available. */
-    font?: Shape["font"];
-}
-/**
- * Prepare text for printing: strip ANSI escape sequences, collapse horizontal
- * whitespace runs, fold unsupported symbols (including box drawing to ASCII),
- * preserve Unicode glyphs that either the selected font or embedded Silver
- * fallback can render, and drop decorative emoji instead of printing `?`.
- */
-export declare function normalize(text: string, options?: NormalizeOptions): string;
-/**
- * Scan text with the same font-aware path as {@link normalize}; unsafe means
- * more than 5% of graphic characters would hit the `?` fallback.
- */
-export declare function scanRenderability(text: string, options?: NormalizeOptions): {
-    isSafe: boolean;
-    unrenderableRatio: number;
-};
-/**
- * Wrap each maximal alphabetic run that is a stopword in {@link DIM_ON} /
- * {@link DIM_OFF} so it prints in dim gray ink. Spans that are already dim
- * (e.g. archived tool output) pass through untouched — wrapping there would
- * terminate the enclosing dim span early. Markers are zero-width, so the
- * visible glyph count is unchanged.
- */
-export declare function dimStopwords(text: string): string;
-/**
- * Greedy word-wrap, no mid-word breaks (hard split only for width+ words) —
- * ported verbatim from `research/exp14_bestgpt.py` `wrap()`. Zero-width dim
- * markers count toward word length here; serialized history places them at
- * word boundaries, so the drift is at most one cell per affected line.
- */
-export declare function wrap(text: string, width: number, wideCells?: boolean): string[];
-export declare function geometry(shape: Shape, size?: number): Geometry;
-/** Render one snapcompact frame from already-normalized text. Doc shapes
- *  (`columns === 2`) expect one page of `\n`-joined pre-wrapped lines. */
-export declare function render(text: string, shape: Shape, size?: number): Promise<RenderedFrame>;
-/** Options for {@link renderMany} and {@link frames}. */
-export interface RenderManyOptions {
-    /** Explicit shape; wins over `model`. */
-    shape?: Shape;
-    /** Model whose provider API and id select the frame shape. */
-    model?: ShapeTarget;
-    /** Frame edge in px; defaults to the shape's `frameSize`. */
-    frameSize?: number;
-    /** Hard cap on frames produced; omit for unbounded (caller decides usage). */
-    maxFrames?: number;
-}
-/**
- * Render arbitrary text into snapcompact PNG frames as LLM image blocks
- * (first page first). Empty/whitespace-only input yields no frames.
- */
-export declare function renderMany(text: string, options?: RenderManyOptions): Promise<ImageContent[]>;
-/** Frames needed to hold `text` at the given shape/size, without rendering.
- *  For doc shapes this wraps the text once and counts pages of `2 * rows`
- *  lines; for grid shapes it divides by the frame capacity. */
-export declare function frames(text: string, options?: Pick<RenderManyOptions, "shape" | "model" | "frameSize">): number;
-/** Validate and extract a persisted frame archive from `preserveData`. */
-export declare function getPreservedArchive(preserveData: Record<string, unknown> | undefined): Archive | undefined;
-/** Drop the persisted frame archive ({@link PRESERVE_KEY}) from `preserveData`,
- *  returning the remaining state — or `undefined` when nothing else remains, so
- *  an empty `{}` is never persisted. Callers strip the archive once its frames
- *  have been migrated into a new compaction's text, preventing the stale frames
- *  from leaking back into the rebuilt context. */
-export declare function stripPreservedArchive(preserveData: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
-/** Extract persisted archive source text as plain text for LLM summarization. */
-export declare function archiveSourceText(archive: Archive): string | undefined;
-/** Build the text used to choose and preflight a font-aware snapcompact shape. */
-export declare function renderabilityProbeText(serialized: string, previousPreserveData?: Record<string, unknown>, previousSummary?: string): string;
-/** Options for reconstructing a persisted snapcompact archive into prompt blocks. */
-export interface HistoryBlockOptions {
-    /** Hard cap on image base64 bytes attached to one rebuilt provider request. */
-    maxFrameDataBytes?: number;
-}
-/** Convert archive frames into LLM image blocks (oldest first). */
-export declare function images(archive: Archive): ImageContent[];
-/** Ordered archive blocks for a compaction summary message, oldest to newest:
- *  the oldest text region, the imaged middle, then the newest text region.
- *  Runtime-only; reconstructed from {@link Archive} on each context rebuild
- *  instead of persisted on the session entry. */
-export declare function historyBlocks(archive: Archive, options?: HistoryBlockOptions): (TextContent | ImageContent)[];
-/**
- * Run a snapcompact compaction over prepared messages. Fully local: serializes
- * the discarded history, appends it to the accumulated archive source text, and
- * re-renders that source into an ordered history layout: plain text at the
- * oldest edge, imaged middle, then plain text at the newest edge. The imaged
- * middle itself foveates (HQ/LQ/HQ) when it grows large.
- *
- * The full kept source persists on the archive (`text`) so each later compaction
- * unfolds and re-renders it coherently alongside the newly archived history.
- *
- * If the previous compaction was text-based, its summary is printed at the head
- * of the archive as `[Summary of earlier history]` so no continuity is lost.
- */
-export declare function compact<TMessage = Message>(preparation: CompactionPreparation<TMessage>, options?: Options<TMessage>): Promise<CompactionResult>;