@linxiraos/zeta-compact 0.0.0-stage → 1.4.12

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+## [Unreleased]
+
+## [1.4.12] - 2026-11-08
+
+- Synced with upstream OMP v18.18.0.
+- Released as part of Zeta 1.4.12; no package-specific user-visible changes.
+
+## [1.4.11] - 2026-11-06
+
+- Released as part of Zeta 1.4.11; no package-specific user-visible changes.
+
+## [1.4.10] - 2026-11-05
+
+- Released as part of Zeta 1.4.10; no package-specific user-visible changes.
+
+## [1.4.9] - 2026-11-03
+
+- Synced with upstream OMP v18.18.0.
+
+## [1.4.7] - 2026-10-30
+
+- Synced with upstream OMP v18.18.0.
+
+## [1.4.5] - 2026-10-28
+
+- Synced with upstream OMP v18.18.0.
+
+## [1.4.4] - 2026-10-26
+
+- Released as part of Zeta 1.4.4; no package-specific user-visible changes.
+
+## [1.4.3] - 2026-10-25
+
+- Released as part of Zeta 1.4.3; no package-specific user-visible changes.
+
+## [1.4.2] - 2026-10-24
+
+- Version alignment with the 1.4.2 release line (no behavioral changes).
+
+## [1.4.1] - 2026-10-23
+
+- Version alignment with the 1.4.1 release line (no behavioral changes).
+
+## [1.4.0] - 2026-10-21
+
+- Version line moves to 1.4.0 with the rest of the suite; no user-visible change in this package.
+
+## [1.3.2] - 2026-10-19
+
+- Version line moves to 1.3.2 with the rest of the suite; no user-visible change in this package.
+
+## [1.3.1] - 2026-10-19
+
+- 版本线推进至 1.3.1；本版无独立用户可见变化。
+
+## [1.3.0] - 2026-10-18
+
+### 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))
+- Added `viewWithoutThinking()`, `textWithoutThinking()`, `readerIncludesThinking()` and an optional `Archive.withoutThinking` variant, so an archive rendered with reasoning can be read by a model that must not see it; without a stored variant the view keeps only reasoning-free text and no frames ([#15436](https://github.com/can1357/oh-my-pi/pull/15436) 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))
+- Fixed re-rendering an archive without reasoning keeping every paragraph after the first of a multi-paragraph `¶think:` section ([#15436](https://github.com/can1357/oh-my-pi/pull/15436) by [@will-bogusz](https://github.com/will-bogusz))
+
+## [1.2.0] - 2026-10-12
+
+- 版本线推进至 1.1.28；本版无独立用户可见变化。
+
+## [1.1.27] - 2026-10-07
+
+- 版本线推进至 1.1.27；本版无独立用户可见变化。
+
+### Breaking Changes
+
+- `maxFramesForDataBudget()` now takes the frame shape instead of a byte budget, so the default 1568px shapes get 26 frames instead of 17 ([#14277](https://github.com/can1357/oh-my-pi/pull/14277) by [@will-bogusz](https://github.com/will-bogusz)).
+
+### Added
+
+- Added `frameBilling`, `frameTokens` and `frameBillingKey`, which price a rendered frame at what the model reading it is billed ([#14291](https://github.com/can1357/oh-my-pi/pull/14291) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed snapcompact frame token estimates following the gateway instead of the model reading the frames, which mispriced Claude behind OpenRouter or Vertex and Claude 4.6 and older ([#14286](https://github.com/can1357/oh-my-pi/pull/14286) by [@will-bogusz](https://github.com/will-bogusz)).
+
+## [1.1.25] - 2026-10-03
+
+- 版本线推进至 1.1.25；本版无独立用户可见变化。
+
+## [1.1.24] - 2026-10-03
+
+- 上游 v18.4.11 集成；本轮无用户可见变更。
+
+## [1.1.22] - 2026-09-30
+
+- 随 1.1.22 版本线发布;无面向用户的行为变化。
+
+## [1.1.19] - 2026-09-22
+
+- 版本线推进;本版无独立用户可见变化。
+
+## [1.1.18] - 2026-09-22
+
+- 包元数据:author/maintainer 更新为 Linxira-OS,LICENSE 追加 Linxira-OS 版权行(发行面变更)。
+
+## [1.1.16] - 2026-09-19
+
+- 上游 v18.2.5 维护同步。

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/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @linxiraos/zeta-compact
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bitmap-frame context compression for vision-capable LLMs.
+
+Instead of asking an LLM to summarize discarded conversation history, snapcompact serializes it and renders the text into dense PNG frames of pixel-font glyphs that vision models read back directly. 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 (`@linxiraos/pi-natives`).
+
+Built for [omp](https://github.com/can1357/oh-my-pi)'s compaction pipeline, but the rendering API works on arbitrary text.
+
+## How it works
+
+1. Discarded history is serialized to compact text (`serializeConversation`), with per-tool-result and per-argument character caps.
+2. Text is normalized for the selected native font (`normalize`): ANSI sequences stripped, whitespace collapsed, newline runs folded into a single full-block glyph, box drawing and compatibility symbols folded to ASCII, semantic emoji folded to ASCII labels, decorative emoji dropped, and non-Latin glyphs preserved when either the selected font or the embedded Silver fallback can render them.
+3. Pages of text are rasterized into PNG frames (`render` / `renderMany`). Frame width is fixed per shape; height hugs the rows actually printed, with a 64px minimum so short final frames remain valid for vision processors.
+4. Frames persist in the compaction entry's `preserveData` and are re-attached to the summary message on every context rebuild.
+
+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                         |
+
+`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
+bun add @linxiraos/zeta-compact
+```
+
+Ships TypeScript source directly (no build step); requires Bun ≥ 1.4.4.
+
+## Usage
+
+Render arbitrary text into LLM image blocks:
+
+```ts
+import { renderMany, frames, resolveShape } from "@linxiraos/zeta-compact";
+
+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
+```
+
+Run a full compaction pass over prepared messages:
+
+```ts
+import { compact } from "@linxiraos/zeta-compact";
+
+const result = await compact(preparation, { model });
+// result.summary        — short "resume prior conversation" lead-in, reading guide, and FILES section
+// result.preserveData   — bounded archive source + rendered image middle
+```
+
+## API surface
+
+- **Compaction**: `compact`, `CompactionPreparation`, `CompactionResult`, `getPreservedArchive`, `images`, `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`, `frameDataBytesBudget`, `MAX_FRAMES_DEFAULT`, `FRAME_TOKEN_ESTIMATE`, `frameBilling`, `frameTokens`, `frameBillingKey`, `plannedFrameTokens`, `HQ_EDGE_FRAMES`
+- **File ops**: `createFileOps`, `computeFileLists`, `upsertFileOperations`
+
+## References
+
+- [Monorepo README](https://github.com/Linxira-OS/linxira-zeta#readme)
+- [Compaction architecture](../../docs/compaction.md)
+- [CHANGELOG](./CHANGELOG.md)