Repository navigation
v0.24.0
Pentool v0.24.0 — Agent previews and a faster CLI
Plan and acceptance criteria: docs/roadmap/v0.24.0/TASKS.md. Exported bytes
are unchanged; new flags and JSON fields are additive.
Speed
The agent loop: add a shape, then look at the whole page at 1024 px, ten
steps. Milliseconds per step on GitHub's CI runners, against the published
v0.23.0 binaries (scripts/bench-agent-loop.py). Every image is
byte-identical to v0.23.0's export.
| Document | v0.23.0 edit+export | v0.24.0 --preview |
v0.24.0 session |
|---|---|---|---|
| Linux, 55 layers | 352 | 129 (2.7x) | 110 (3.2x) |
| Windows, 55 layers | 274 | 142 (1.9x) | 119 (2.3x) |
| macOS, 55 layers | 412 | 216 (1.9x) | 155 (2.7x) |
| Linux, small | 44 | 35 (1.3x) | 18 (2.4x) |
| Windows, small | 53 | 38 (1.4x) | 22 (2.4x) |
| macOS, small | 85 | 79 (1.1x) | 38 (2.2x) |
A single uncached export of a large page is about 1.2x faster (multithreaded
blur, gradients and blending); most of the gain comes from fewer processes and
reusing unchanged layers.
Changes
- Agent loop (add a shape, then look at the whole page at 1024 px; Windows,
ms per step, v0.23.0 edit+export / v0.24.0--preview/ v0.24.0 session):
small document 498 / 361 / 98, 55-layer document 780 / 423 / 300. Every
image is byte-identical to v0.23.0's export.scripts/bench-agent-loop.py
reproduces it, and CI runs it on all three OSes. --previewon every mutating command and its dry run: one call edits the
document and returns a PNG of the changed page, rendered by the normal
export renderer at 1024 px on the long edge. The JSON result gains a
top-levelpreviewobject withpath,page,width,height,scale,
revision(always the revision the same call wrote) anddry_run.
--preview-size PX(1 to 8192) sets the long edge,--preview-out PATH
chooses the file,--pagechooses the page (otherwise the first page that
changed), andPENTOOL_PREVIEW=1turns previews on for a whole session.
Images go to.pentool/preview/beside the document, which keeps the 32
newest. A failed preview is reported aspreview.errorand never fails an
edit that already committed. Without previews every command prints exactly
the same bytes as before; the Studio server never renders CLI previews.- Previews zoom in on the change: when the edited or added objects cover
less than half the page, the image shows them plus padding at up to 8x and
the result addsfocus(ids,x,y,width,height) and a 256 px
whole-pagethumbnail. The focused image is a crop of the normal render at
the reported scale, so every pixel matchesexport --scale.--focus ID
(repeatable) picks the objects and--no-focusshows the whole page; an
unknown ID is reported aspreview.error. pentool preview DOCrenders the document as it is on disk, read-only,
with the samepreviewobject (nodry_run): the whole page, or the
--focusobjects with a thumbnail;--page,--max-size PXand
--out PATHas above.--annotatedraws object IDs and bounds on the preview image (never on
exports or the thumbnail) and addsannotationswithlabels(id,
color, box in preview pixels) andtruncated. It labels every object on
a whole-page preview, or the focused objects, at most 50, and implies
--preview.--compare REV|FILE|beforerenders the same view of a history revision, a
.penfile or the state before the change, and addscomparewith
changed_pixels,changed_pct,changed_bboxand, when pixels changed, a
diffimage (changed pixels in red). It implies--preview.export --max-size PXpicks the export scale so the longest page edge is at
mostPXpixels (1 to 8192; with--all-pagesthe largest page decides),
instead of the agent guessing--scale. The result addsmax_sizeand the
chosenscale. It cannot be combined with--scale, and a bound that would
need a scale below 0.1 fails with[limit-exceeded]before anything is
written. Exports without it print the same bytes as before.- Previews and exports of composite (v6) documents keep finished layer
surfaces in.pentool/cache/render-*beside the document, so the next CLI
call re-renders only the layers that changed (warm preview of a 55-layer
1200x675 landscape: 335 ms to 209 ms). Output bytes are identical with and
without it. Entries are checksummed (a damaged one is a miss), the
directory is bounded to 256 MB by least recent use and is replaced when the
binary changes.--no-cacheorPENTOOL_CACHE=0turns it off. pentool session --jsonlruns one command per stdin line (a JSON array of
arguments, or{"id", "args"}) and prints one JSON reply per line
(ok,resultortext,error, and theid), keeping fonts and layer
surfaces warm between lines. Commands use the same transaction, lock and
revision-guard path as separate processes and write identical documents.
On the 55-layer landscape (fast build, Windows):tree4 ms per line
against 27 ms per process; edit plus whole-page preview 89 ms per line.- Gradient fills, blur effects and layer blending run on up to 16 threads
(std::thread::scope, no new dependency). Every row is computed by the
same arithmetic as on one thread, so exports are byte-identical for any
thread count;PENTOOL_THREADS=Nsets it and1forces one thread.
Uncached export of the 55-layer landscape at scale 2: 1315 ms to 1064 ms. - Faster start for renders. Layers without text no longer build a font
database, and text layers share one instead of rebuilding it per layer
(in-process time of a scale-0.1 landscape export: about 50 ms to 37 ms).
On Windows the installed-font list is kept in the per-user cache
(%LOCALAPPDATA%\pentool\fonts.bin) and used only while the listing of
font files in the font folders is unchanged (other files there are not
even looked at): loading it takes about 5 ms against 27–77 ms for a warm
scan and about 340 ms for a cold one. Linux and macOS keep scanning: Linux
font folders come from fontconfig's configuration, and on macOS checking
the system asset folders cost more than the scan in CI. Output bytes are
unchanged.
Full Changelog: v0.23.0...v0.24.0