@oh-my-pi/snapcompact 18.10.2 → 18.10.3

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [18.10.3] - 2026-10-12
+
+### Breaking Changes
+
+- `providerImageBudget(provider)` and `providerFrameBudget(provider)` became `providerImageBudget(model)` and `providerFrameBudget(model)`, and `maxFramesForDataBudget(shape)` became `maxFramesForDataBudget(shape, budget)` with a required byte budget ([#15434](https://github.com/can1357/oh-my-pi/pull/15434) by [@will-bogusz](https://github.com/will-bogusz))
+- Removed `PROVIDER_IMAGE_BUDGETS` and `FRAME_DATA_BYTES_BUDGET`: image counts come from the catalog's `image-count-budget` rules, and frame byte budgets from `frameDataBytesBudget(model)` (`DEFAULT_FRAME_DATA_BYTES_BUDGET` where the host has none) ([#15434](https://github.com/can1357/oh-my-pi/pull/15434) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Added
+
+- Added `plannedFrameTokens` and `Shape.frameTokensVerified`: archive sizing charges a frame its own price when the reader's `image-tokenization` rule is `verified`, and at least `FRAME_TOKEN_ESTIMATE` otherwise ([#15442](https://github.com/can1357/oh-my-pi/pull/15442) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed snapcompact frames for Claude and GPT on Cursor, including its `default` (Auto) route, being drawn at 1568–1932px, which Cursor shrank to 1024px before the model read them; frames now render at the host's catalog `image-max-edge` ([#15448](https://github.com/can1357/oh-my-pi/pull/15448) by [@will-bogusz](https://github.com/will-bogusz))
+
 ## [18.6.3] - 2026-10-06
 
 ### Breaking Changes

package/README.md

@@ -15,17 +15,19 @@ Built for [omp](https://github.com/can1357/oh-my-pi)'s compaction pipeline, but
 
 Frame shapes are provider-aware, chosen by SQuAD recall evals (see `research/`) against real provider billing:
 
-| Reader | Default shape | Notes |
-| --- | --- | --- |
-| Anthropic | `11on16-bw` | X.org 8x13 glyphs on an 11px advance; high-res Claude lines get 1932px frames |
-| Google | `8on22-bw` @2048 | X.org 8x13 glyphs on a 22px pitch; Gemini bills a fixed per-image budget, so larger frames are free chars |
-| OpenAI | `8on22-bw` | X.org 8x13 glyphs on a 22px pitch, sent at `detail: "original"` |
-| Unknown | Anthropic shape | Per-provider image-count budgets guard against gateways that silently drop frames |
+| Reader    | Default shape    | Notes                                                                                                     |
+| --------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
+| Anthropic | `11on16-bw`      | X.org 8x13 glyphs on an 11px advance; high-res Claude lines get 1932px frames                             |
+| Google    | `8on22-bw` @2048 | X.org 8x13 glyphs on a 22px pitch; Gemini bills a fixed per-image budget, so larger frames are free chars |
+| OpenAI    | `8on22-bw`       | X.org 8x13 glyphs on a 22px pitch, sent at `detail: "original"`                                           |
+| Unknown   | Anthropic shape  | Per-provider image-count budgets guard against gateways that silently drop frames                         |
 
-`resolveShape({ api, id })` matches the model id, not just the wire API — a Claude routed through Vertex or OpenRouter keeps its Claude shape. Frames are priced by the reading model's lineage: its catalog `image-tokenization` rule (so that Claude is billed as Claude, and Opus 4.6 under the standard 1,568-token tier), falling back to the catalog rule for the wire API carrying the request when the lineage has none. A reader with neither costs `FRAME_TOKEN_ESTIMATE` per frame.
+`resolveShape({ api, id })` matches the model id, not just the wire API — a Claude routed through Vertex or OpenRouter keeps its Claude shape. Frames are priced by the reading model's lineage: its catalog `image-tokenization` rule (so that Claude is billed as Claude, and Opus 4.6 under the standard 1,568-token tier), falling back to the catalog rule for the wire API carrying the request when the lineage has none. A reader with neither costs `FRAME_TOKEN_ESTIMATE` per frame. Archive sizing (`plannedFrameTokens`) charges each frame its own price when the rule is `verified` against provider billing, and at least `FRAME_TOKEN_ESTIMATE` otherwise.
 
 Bitmap shapes keep their provider-tuned geometry and draw missing glyphs through the embedded Silver TrueType fallback one character at a time; East Asian (CJK/Kana/Hangul) glyphs render full-width across two cells so they stay legible in the narrow ASCII grid. Selecting `silver16-bw` uses Silver for the whole frame.
 
+A host that downscales images before the model reads them (catalog `image-max-edge`; Cursor fits Claude and GPT images into 1024×1024) gets frames rendered at that edge, forced variants included, so the glyphs reach the model at the size they were drawn.
+
 ## Install
 
 ```sh
@@ -42,8 +44,8 @@ Render arbitrary text into LLM image blocks:
 import { renderMany, frames, resolveShape } from "@oh-my-pi/snapcompact";
 
 const images = renderMany(longText, { model }); // ImageContent[], first page first
-const count = frames(longText, { model });      // frame count without rendering
-const shape = resolveShape(model);              // eval-optimal Shape for the reader
+const count = frames(longText, { model }); // frame count without rendering
+const shape = resolveShape(model); // eval-optimal Shape for the reader
 ```
 
 Run a full compaction pass over prepared messages:
@@ -58,11 +60,11 @@ const result = await compact(preparation, { model });
 
 ## API surface
 
-- **Compaction**: `compact`, `CompactionPreparation`, `CompactionResult`, `getPreservedArchive`, `images`, `historyBlocks`
+- **Compaction**: `compact`, `CompactionPreparation`, `CompactionResult`, `getPreservedArchive`, `images`, `historyBlocks`, `capFrameDataBytes`
 - **Rendering**: `render`, `renderMany`, `frames`, `geometry`
 - **Shapes**: `SHAPES`, `SHAPE_VARIANTS`, `resolveShape`, `resolveShapeForText`, `idealShapeVariant`, `isShape`, `isShapeVariantName`
 - **Text**: `serializeConversation`, `normalize`, `scanRenderability`, `renderabilityProbeText`, `dimStopwords`, `wrap`
-- **Budgets**: `providerImageBudget`, `MAX_FRAMES_DEFAULT`, `FRAME_TOKEN_ESTIMATE`, `frameBilling`, `frameTokens`, `frameBillingKey`, `HQ_EDGE_FRAMES`
+- **Budgets**: `providerImageBudget`, `frameDataBytesBudget`, `MAX_FRAMES_DEFAULT`, `FRAME_TOKEN_ESTIMATE`, `frameBilling`, `frameTokens`, `frameBillingKey`, `plannedFrameTokens`, `HQ_EDGE_FRAMES`
 - **File ops**: `createFileOps`, `computeFileLists`, `upsertFileOperations`
 
 ## References

package/dist/types/snapcompact.d.ts

@@ -32,11 +32,9 @@
  *   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`. `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.
+ * - **Unknown providers** default to `8on22-bw`. `providerImageBudget` caps
+ *   per-request images at the deployment's catalog `image-count-budget`, so
+ *   inline imaging cannot flood a request with attachments.
  *
  * The per-frame token estimate follows the reading model's catalog
  * `image-tokenization` rule (its lineage, not the gateway), so Claude behind
@@ -44,13 +42,17 @@
  * Models without a lineage rule fall back to the catalog rule for their wire
  * API; a reader with neither costs {@link FRAME_TOKEN_ESTIMATE} per frame.
  *
+ * A host that downscales every image before the model reads it (catalog
+ * `image-max-edge`, e.g. Cursor) gets frames rendered at that edge instead,
+ * so glyphs reach the model at the size they were drawn.
+ *
  * The whole pass is local and deterministic — no LLM call, no API key, no
  * latency beyond rendering. Rasterization and PNG encoding happen in native
  * code (`renderSnapcompactPng` in `crates/pi-natives/src/snapcompact.rs`).
  * Frames persist in the compaction entry's `preserveData` and are
  * re-attached to the compaction summary message on every context rebuild.
  */
-import type { Api, ImageContent, Message, TextContent } from "@oh-my-pi/pi-ai";
+import type { Api, ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
 import { type ImageSize, type ImageTokenization, type ImageTokenizationTarget } from "@oh-my-pi/pi-catalog/compat/image-tokenization";
 /** One eval-validated frame shape: font, cell, ink, repetition, and size. */
 export interface Shape {
@@ -78,11 +80,13 @@ export interface Shape {
     frameSize: number;
     /** Per-frame billed-token estimate for the shape's target provider. */
     frameTokenEstimate: number;
+    /** `frameTokenEstimate` comes from a catalog rule measured against provider billing. */
+    frameTokensVerified?: boolean;
     /** 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">;
+export type ShapeGeometry = Omit<Shape, "frameTokenEstimate" | "frameTokensVerified" | "imageDetail">;
 /**
  * Frame variants exercised by the SQuAD evals in `research/` that the native
  * renderer reproduces faithfully, keyed by their research names. Font codes:
@@ -269,6 +273,11 @@ export declare function frameBilling(target: ShapeTarget | undefined): FrameBill
 export declare function frameBillingKey(billing: FrameBilling): string;
 /** Billed-token estimate for one rendered frame of `size` under `billing`. */
 export declare function frameTokens(billing: FrameBilling, size: ImageSize): number;
+/**
+ * Per-frame tokens archive sizing charges `shape`: its own price when provider
+ * billing verified it, else at least {@link FRAME_TOKEN_ESTIMATE}.
+ */
+export declare function plannedFrameTokens(shape: Shape): number;
 /** 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.
@@ -312,7 +321,8 @@ export interface ShapeTarget {
  * 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
+ * the API family's winner when the model is unmeasured. Either way the frame
+ * is no wider than the host's catalog `image-max-edge`. Billing (token
  * estimate, detail hint) is computed for the resolved frame size from the
  * model's catalog image rule. Accepts a full pi-ai `Model` or any
  * `{ api, id }` subset.
@@ -340,44 +350,46 @@ export declare const MAX_FRAMES_DEFAULT = 80;
  *  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 for archive sizing and for frames of
- *  unknown size — 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}. */
+/** Conservative per-frame token estimate for sizing archives whose frame price
+ *  is not billing-verified, and for frames of unknown size — 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
+/** Frame payload cap for a deployment without a catalog `inline-image-byte-budget`:
+ *  an unmeasured backend can accept the HTTP body and still 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} for frames
- *  rendered by `shape`. {@link AREA_PRICED_VARIANTS} below 1932px are charged
+export declare const DEFAULT_FRAME_DATA_BYTES_BUDGET = 3000000;
+/** Base64 image bytes the archive frames riding every request to `model` may
+ *  carry: half the deployment's inline-image byte budget, else
+ *  {@link DEFAULT_FRAME_DATA_BYTES_BUDGET}. Frames are the oldest images in the
+ *  request, so the send-time byte clamp evicts them first; the other half stays
+ *  free for live screenshots. */
+export declare function frameDataBytesBudget(model: Model | undefined): number;
+/** Frame-count cap a `budget` of base64 bytes implies for frames rendered by
+ *  `shape`. {@link AREA_PRICED_VARIANTS} below 1932px are charged
  *  {@link FRAME_DATA_BYTES_ESTIMATE} scaled by pixel area; every other shape
  *  pays the full estimate. */
-export declare function maxFramesForDataBudget(shape: ShapeGeometry): number;
+export declare function maxFramesForDataBudget(shape: ShapeGeometry, budget: 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). */
+/** Safe floor for a deployment whose catalog rules set no `image-count-budget`
+ *  (strictest mainstream measured: Groq ~5). */
 export declare const DEFAULT_PROVIDER_IMAGE_BUDGET = 5;
-/** Per-request image budget for `provider`; unknown providers get the floor. */
-export declare function providerImageBudget(provider: string | undefined): number;
-/** Archive frame cap for `provider`: image budget, never above {@link MAX_FRAMES_DEFAULT}. */
-export declare function providerFrameBudget(provider: string | undefined): number;
+/** Most images one request to `model`'s deployment may carry, archive,
+ *  system-prompt and tool-result imaging combined. */
+export declare function providerImageBudget(model: Model | undefined): number;
+/** Archive frame cap for `model`: its image budget, never above {@link MAX_FRAMES_DEFAULT}. */
+export declare function providerFrameBudget(model: Model | undefined): number;
+/** Whether `model` may get a fresh `read` result as frames (catalog `snapcompact-image-reads`, opt-in). */
+export declare function readerImagesReadResults(model: Model): boolean;
 /** 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. */
@@ -620,6 +632,12 @@ export declare function images(archive: Archive): ImageContent[];
  *  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)[];
+/**
+ * Re-applies a smaller frame byte budget to blocks {@link historyBlocks} already built: keeps the newest frames that
+ * fit, priced as {@link historyBlocks} prices them, and replaces each run of dropped frames with one omission notice.
+ * Returns `blocks` itself when every frame fits.
+ */
+export declare function capFrameDataBytes(blocks: (TextContent | ImageContent)[], maxFrameDataBytes: number): (TextContent | ImageContent)[];
 /**
  * Run a snapcompact compaction over prepared messages. Fully local: serializes
  * the discarded history, appends it to the accumulated archive source text, and

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/snapcompact",
-	"version": "18.10.2",
+	"version": "18.10.3",
 	"description": "Bitmap-frame context compression for vision-capable LLMs",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -34,11 +34,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.10.2",
-		"@oh-my-pi/pi-catalog": "18.10.2",
-		"@oh-my-pi/pi-natives": "18.10.2",
-		"@oh-my-pi/pi-utils": "18.10.2",
-		"@oh-my-pi/pi-wire": "18.10.2"
+		"@oh-my-pi/pi-ai": "18.10.3",
+		"@oh-my-pi/pi-catalog": "18.10.3",
+		"@oh-my-pi/pi-natives": "18.10.3",
+		"@oh-my-pi/pi-utils": "18.10.3",
+		"@oh-my-pi/pi-wire": "18.10.3"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/snapcompact.ts

@@ -32,11 +32,9 @@
  *   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`. `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.
+ * - **Unknown providers** default to `8on22-bw`. `providerImageBudget` caps
+ *   per-request images at the deployment's catalog `image-count-budget`, so
+ *   inline imaging cannot flood a request with attachments.
  *
  * The per-frame token estimate follows the reading model's catalog
  * `image-tokenization` rule (its lineage, not the gateway), so Claude behind
@@ -44,6 +42,10 @@
  * Models without a lineage rule fall back to the catalog rule for their wire
  * API; a reader with neither costs {@link FRAME_TOKEN_ESTIMATE} per frame.
  *
+ * A host that downscales every image before the model reads it (catalog
+ * `image-max-edge`, e.g. Cursor) gets frames rendered at that edge instead,
+ * so glyphs reach the model at the size they were drawn.
+ *
  * 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`).
@@ -51,14 +53,18 @@
  * re-attached to the compaction summary message on every context rebuild.
  */
 
-import type { Api, ImageContent, Message, TextContent } from "@oh-my-pi/pi-ai";
+import type { Api, ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
+import { reachesOfficialEndpoint } from "@oh-my-pi/pi-ai/providers/anthropic-state";
+import { resolveCatalogPolicy } from "@oh-my-pi/pi-catalog/compat/catalog-policy";
 import {
 	type ImageSize,
 	type ImageTokenization,
 	type ImageTokenizationTarget,
 	imageTokens,
+	resolveImageMaxEdge,
 	resolveImageTokenization,
 } from "@oh-my-pi/pi-catalog/compat/image-tokenization";
+import { resolveImageCountBudget, resolveInlineImageByteBudget } from "@oh-my-pi/pi-catalog/compat/request-size";
 import { classifyModel, compareRevision, parseRevision } from "@oh-my-pi/pi-catalog/identity";
 import { renderSnapcompactPng, snapcompactSupportedChars } from "@oh-my-pi/pi-natives";
 import { formatGroupedPaths, prompt } from "@oh-my-pi/pi-utils";
@@ -96,12 +102,14 @@ export interface Shape {
 	frameSize: number;
 	/** Per-frame billed-token estimate for the shape's target provider. */
 	frameTokenEstimate: number;
+	/** `frameTokenEstimate` comes from a catalog rule measured against provider billing. */
+	frameTokensVerified?: boolean;
 	/** 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">;
+export type ShapeGeometry = Omit<Shape, "frameTokenEstimate" | "frameTokensVerified" | "imageDetail">;
 
 /**
  * Frame variants exercised by the SQuAD evals in `research/` that the native
@@ -273,7 +281,22 @@ export function frameTokens(billing: FrameBilling, size: ImageSize): number {
 function priceShape(base: ShapeGeometry, target: ShapeTarget | undefined): Shape {
 	const billing = frameBilling(target);
 	const frameTokenEstimate = frameTokens(billing, { width: base.frameSize, height: base.frameSize });
-	return { ...base, frameTokenEstimate, ...(billing.imageDetail && { imageDetail: billing.imageDetail }) };
+	return {
+		...base,
+		frameTokenEstimate,
+		...(billing.rule?.verified && { frameTokensVerified: true }),
+		...(billing.imageDetail && { imageDetail: billing.imageDetail }),
+	};
+}
+
+/**
+ * Per-frame tokens archive sizing charges `shape`: its own price when provider
+ * billing verified it, else at least {@link FRAME_TOKEN_ESTIMATE}.
+ */
+export function plannedFrameTokens(shape: Shape): number {
+	return shape.frameTokensVerified
+		? shape.frameTokenEstimate
+		: Math.max(FRAME_TOKEN_ESTIMATE, shape.frameTokenEstimate);
 }
 
 /** Eval-validated shapes, keyed by the provider family they won on. */
@@ -320,6 +343,7 @@ export function isShape(value: unknown): value is Shape {
 		shape.frameSize > 0 &&
 		typeof shape.frameTokenEstimate === "number" &&
 		shape.frameTokenEstimate > 0 &&
+		(shape.frameTokensVerified === undefined || typeof shape.frameTokensVerified === "boolean") &&
 		(detail === undefined || detail === "auto" || detail === "low" || detail === "high" || detail === "original")
 	);
 }
@@ -414,16 +438,23 @@ export interface ShapeTarget {
  * 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
+ * the API family's winner when the model is unmeasured. Either way the frame
+ * is no wider than the host's catalog `image-max-edge`. Billing (token
  * estimate, detail hint) is computed for the resolved frame size from the
  * model's catalog image rule. Accepts a full pi-ai `Model` or any
  * `{ api, id }` subset.
  */
 export function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape {
-	if (variant && variant !== "auto") return priceShape(SHAPE_VARIANTS[variant], model);
+	if (variant && variant !== "auto") return priceShape(fitHostImageEdge(SHAPE_VARIANTS[variant], model), model);
 	const ideal = model?.id ? idealShapeVariant(model.id) : undefined;
 	const base = SHAPE_VARIANTS[ideal?.variant ?? FAMILY_VARIANT[apiFamily(model?.api)]];
-	return priceShape(ideal?.frameSize ? { ...base, frameSize: ideal.frameSize } : base, model);
+	return priceShape(fitHostImageEdge(ideal?.frameSize ? { ...base, frameSize: ideal.frameSize } : base, model), model);
+}
+
+/** Shrink `base` to the longest image edge `target`'s host passes to the model. */
+function fitHostImageEdge(base: ShapeGeometry, target: ShapeTarget | undefined): ShapeGeometry {
+	const maxEdge = target ? resolveImageMaxEdge(target) : undefined;
+	return maxEdge !== undefined && base.frameSize > maxEdge ? { ...base, frameSize: maxEdge } : base;
 }
 
 const CJK_HEAVY_MIN_WIDE_CHARS = 8;
@@ -483,11 +514,11 @@ export const MAX_FRAMES_DEFAULT = 80;
  *  text region (newest) — with the denser low-quality tier filling the middle. */
 export const HQ_EDGE_FRAMES = 3;
 
-/** Conservative per-frame token estimate for archive sizing and for frames of
- *  unknown size — 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}. */
+/** Conservative per-frame token estimate for sizing archives whose frame price
+ *  is not billing-verified, and for frames of unknown size — the upper bound
+ *  across shapes: high-res Claude frames hit the 4,784 visual-token cap, billed
+ *  at +5% margin (ceil(4784 * 1.05)). Keeps the overflow guard from
+ *  undercounting a high-res archive at the raised {@link MAX_FRAMES_DEFAULT}. */
 export const FRAME_TOKEN_ESTIMATE = 5024;
 
 /** Conservative upper bound for one persisted frame's base64 payload. The
@@ -496,22 +527,32 @@ export const FRAME_TOKEN_ESTIMATE = 5024;
  *  standing request bodies at large context windows. */
 export const FRAME_DATA_BYTES_ESTIMATE = 170_000;
 
-/** Maximum snapcompact image base64 carried in every rebuilt provider request.
- *  Above this, provider backends can accept the HTTP body but fail mid-stream
+/** Frame payload cap for a deployment without a catalog `inline-image-byte-budget`:
+ *  an unmeasured backend can accept the HTTP body and still 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 const FRAME_DATA_BYTES_BUDGET = 3_000_000;
+export const DEFAULT_FRAME_DATA_BYTES_BUDGET = 3_000_000;
+
+/** Base64 image bytes the archive frames riding every request to `model` may
+ *  carry: half the deployment's inline-image byte budget, else
+ *  {@link DEFAULT_FRAME_DATA_BYTES_BUDGET}. Frames are the oldest images in the
+ *  request, so the send-time byte clamp evicts them first; the other half stays
+ *  free for live screenshots. */
+export function frameDataBytesBudget(model: Model | undefined): number {
+	const inlineBudget = model ? resolveInlineImageByteBudget(model, reachesOfficialEndpoint(model)) : undefined;
+	return inlineBudget === undefined ? DEFAULT_FRAME_DATA_BYTES_BUDGET : Math.floor(inlineBudget / 2);
+}
 
 /** Default edge variants whose frames shrink with pixel area. Inkier variants
  *  keep the full {@link FRAME_DATA_BYTES_ESTIMATE} at any frame size. */
 const AREA_PRICED_VARIANTS: readonly ShapeGeometry[] = [SHAPE_VARIANTS["8on22-bw"], SHAPE_VARIANTS["11on16-bw"]];
 
-/** Frame-count cap implied by {@link FRAME_DATA_BYTES_BUDGET} for frames
- *  rendered by `shape`. {@link AREA_PRICED_VARIANTS} below 1932px are charged
+/** Frame-count cap a `budget` of base64 bytes implies for frames rendered by
+ *  `shape`. {@link AREA_PRICED_VARIANTS} below 1932px are charged
  *  {@link FRAME_DATA_BYTES_ESTIMATE} scaled by pixel area; every other shape
  *  pays the full estimate. */
-export function maxFramesForDataBudget(shape: ShapeGeometry): number {
+export function maxFramesForDataBudget(shape: ShapeGeometry, budget: number): number {
 	const areaPriced = AREA_PRICED_VARIANTS.some(
 		variant =>
 			variant.font === shape.font &&
@@ -525,7 +566,7 @@ export function maxFramesForDataBudget(shape: ShapeGeometry): number {
 	);
 	const areaRatio = areaPriced ? (shape.frameSize / HIGH_RES_ANTHROPIC_VARIANT.frameSize) ** 2 : 1;
 	const frameBytes = Math.min(FRAME_DATA_BYTES_ESTIMATE, Math.ceil(FRAME_DATA_BYTES_ESTIMATE * areaRatio));
-	return Math.max(1, Math.floor(FRAME_DATA_BYTES_BUDGET / frameBytes));
+	return Math.max(1, Math.floor(budget / frameBytes));
 }
 
 /** Base64 byte length for persisted snapcompact frames. */
@@ -533,36 +574,27 @@ export function frameDataBytes(frames: readonly Pick<Frame, "data">[]): number {
 	return frames.reduce((sum, frame) => sum + frame.data.length, 0);
 }
 
-/**
- * Per-request image-count budgets by provider id. These cap how many images an
- * entire request may carry (archive/system-prompt/tool-result imaging combined).
- * The values are conservative policy caps under the vendor hard limits
- * (Anthropic 100, OpenAI 500, Gemini ~2500); unknown providers fall to a safe
- * floor rather than sending unbounded attachments.
- */
-export const PROVIDER_IMAGE_BUDGETS: Record<string, number> = {
-	anthropic: 90,
-	"amazon-bedrock": 90,
-	openai: 200,
-	"openai-codex": 200,
-	google: 200,
-	"google-vertex": 200,
-	"google-gemini-cli": 200,
-	openrouter: 90,
-	umans: 10,
-};
-
-/** Safe floor for unknown providers (strictest mainstream measured: Groq ~5). */
+/** Safe floor for a deployment whose catalog rules set no `image-count-budget`
+ *  (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;
+/** Most images one request to `model`'s deployment may carry, archive,
+ *  system-prompt and tool-result imaging combined. */
+export function providerImageBudget(model: Model | undefined): number {
+	return (
+		(model ? resolveImageCountBudget(model, reachesOfficialEndpoint(model)) : undefined) ??
+		DEFAULT_PROVIDER_IMAGE_BUDGET
+	);
+}
+
+/** Archive frame cap for `model`: its image budget, never above {@link MAX_FRAMES_DEFAULT}. */
+export function providerFrameBudget(model: Model | undefined): number {
+	return Math.min(providerImageBudget(model), MAX_FRAMES_DEFAULT);
 }
 
-/** 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);
+/** Whether `model` may get a fresh `read` result as frames (catalog `snapcompact-image-reads`, opt-in). */
+export function readerImagesReadResults(model: Model): boolean {
+	return resolveCatalogPolicy(model).snapcompactImageReads === true;
 }
 
 /** Key under `CompactionEntry.preserveData` holding the frame archive. */
@@ -1971,6 +2003,53 @@ export function historyBlocks(archive: Archive, options: HistoryBlockOptions = {
 	return blocks;
 }
 
+/**
+ * Re-applies a smaller frame byte budget to blocks {@link historyBlocks} already built: keeps the newest frames that
+ * fit, priced as {@link historyBlocks} prices them, and replaces each run of dropped frames with one omission notice.
+ * Returns `blocks` itself when every frame fits.
+ */
+export function capFrameDataBytes(
+	blocks: (TextContent | ImageContent)[],
+	maxFrameDataBytes: number,
+): (TextContent | ImageContent)[] {
+	const kept = new Set<number>();
+	let usedBytes = 0;
+	let dropped = false;
+	for (let index = blocks.length - 1; index >= 0; index--) {
+		const block = blocks[index];
+		if (block.type !== "image") continue;
+		if (usedBytes + block.data.length > maxFrameDataBytes) {
+			dropped = true;
+			continue;
+		}
+		usedBytes += block.data.length;
+		kept.add(index);
+	}
+	if (!dropped) return blocks;
+
+	const capped: (TextContent | ImageContent)[] = [];
+	let omittedFrames = 0;
+	let omittedBytes = 0;
+	const flushOmitted = (): void => {
+		if (omittedFrames === 0) return;
+		capped.push({ type: "text", text: omittedFrameNotice(omittedFrames, omittedBytes) });
+		omittedFrames = 0;
+		omittedBytes = 0;
+	};
+	for (let index = 0; index < blocks.length; index++) {
+		const block = blocks[index];
+		if (block.type === "image" && !kept.has(index)) {
+			omittedFrames++;
+			omittedBytes += block.data.length;
+			continue;
+		}
+		flushOmitted();
+		capped.push(block);
+	}
+	flushOmitted();
+	return capped;
+}
+
 // ============================================================================
 // Compaction entry point
 // ============================================================================