One Rust binary, UI in iced (tiny-skia CPU renderer). It runs as a resident tray app: the overlay window is created hidden at start, so a trigger only has to capture the screen and show it.
The code is organised by FEATURE (what the user sees), plus one shared layer and the app shell:
src/
main.rs start, CLI (frozen contract), single instance, Trigger
app/ the iced app shell: App state, Message, update / view dispatch, opening and closing,
keys, every monitor (monitors.rs), the normal windows and pins (windows.rs), the
update experience (updates.rs), the daemon's start (shell.rs); screens/ = the shell's
own screens (toast, tray menu, update card / pill, the Windows setup's window)
features/
circle/ Circle to Search: actions/ (the action registry: crop, copy, save, search in browser,
QR, share, entities), screens/ (overlay canvas, bar, screen edge), app/ (selection,
bar, zoom, actions, quick actions)
text_reading/ the readers (PP-OCR helper, Windows OCR, models), Copy text, app/ (reading state,
word picking), screens/ (model download card)
translate/ one-shot translate (pipeline, erase, draw, glossary, the language table), mt/ (offline
models), action.rs, screens/ (the translate pill, the language picker)
live_translate/ the click-through layer (platform side), live.rs (frame logic), screens/ (layer, controller)
ask_ai/ providers and clients, the browser provider, ask.rs (the action), chats.rs (history),
app/ (the chat's handlers), screens/ (the chat, the model list)
snip/ the editor (annotate/), capture/ (snip frames, long capture, pins' capture), action.rs,
snip_more.rs, app/ (Snip, More, toolbar, screen tools), screens/ (the flow, toolbar,
Steps strip, long capture and its pop-up, screen tools, studio/: OpenCircle Studio's
window, the same editor on a rail + options bar; its host is app/windows/studio.rs)
song/ song search, its history, screens/
settings/ the Settings window and its pages, previews, the Labs switches (labs.rs)
onboarding/ the first-run steps
live_core/ the live translation core (0.3.0): engine-agnostic, std only (rule 4); live translate runs on it
shared/ what every feature uses and no feature owns
kit/ theme.rs touch.rs the one UI kit and its tokens; the config-to-kit glue; touch as mouse
platform/ the OS: capture core, hotkey/, sys/, autostart, and the windows / monitor / shape / tray glue
config/ app_language/ store/ update/ setup/ history/ log.rs paths.rs secrets.rs net.rs diagnostics.rs
A feature folder holds its logic at its root, its part of the shared App in app/ (impl App blocks:
Rust allows them in any module, so app/ keeps only the dispatch), and its views in screens/.
onboarding/ and settings/ are all UI.
Rules (source scans in app/arch_tests.rs, each proved to fail on a planted violation):
shared/never importsfeatures/orapp/(shared_never_imports_features_or_app).- A feature uses another feature only through that feature's
mod.rs(features_meet_only_through_mod_rs). - Screens never style; only the kit styles; the kit depends only on itself; the OS glue imports no UI; the
backend (every non-UI file) imports no UI; windows are shown only by
platform::windows::show, resized only byplatform::monitor::resize; every text names a bundled face; one scrollbar, one dropdown; every kit press is a focus stop. Words only from the string table (shared/app_language/tests.rs). live_core/names only std and itself (live_core_uses_only_std_and_itself: nocrate::path outside it, nosuper::out of the folder, no Cargo.toml dependency unless onLIVE_CORE_CRATES, empty), so it can move to its own crate as it is (rustc --edition 2024 --test -O src/live_core/mod.rsbuilds and runs its tests alone). Rules 1 and 2 carry a ratchet (SHARED_LEGACY,FEATURE_LEGACY): the files that still break them when the folders were made. The lists only shrink: a file that is clean must leave its list.
Add a feature = one folder + one registry entry:
src/features/<name>/mod.rs(its public face: what other features and the shell may use), its logic beside it,app/for itsimpl Apphandlers,screens/for its views (kit parts only).pub(crate) mod <name>;insrc/features/mod.rs.- One entry in the list that shows it: an action in
features/circle/actions/mod.rs(ACTIONS), a Settings page infeatures/settings/pages/mod.rs(PAGES), a Labs switch infeatures/settings/labs.rs, a tray row inshared/platform/tray.rs(entries), a quick action inshared/config(QuickAction). - Its messages in
app/message.rs, dispatched inapp/update.rsto the feature'sapp/handlers. - Its words in
shared/app_language/strings.rs; its UI files are covered by the word scan (UI_SOURCESthere) and the arch tests (in_uithere:features/*/screens,features/*/app).
| Module | Role |
|---|---|
main.rs |
Argument parsing, single-instance hand-off, starts tray + shortcut + UI. Trigger = what any source asks for. |
shared/platform/hotkey/ |
Global shortcuts from the config (capture + one per quick action; global-hotkey, or the Wayland portal; without the portal the per-desktop fallbacks gnome.rs (GNOME's custom shortcuts) and kde.rs (KDE's KGlobalAccel over D-Bus, also on KDE X11), both kept in step by fallback_sync) and the per-user command socket behind opencircle capture / opencircle run <action>. hotkey::reload(&Config) re-registers after a settings change. Wayland portal ids = Binding::portal_id (a non-default key rides in the id, because GNOME keeps the key it stored under an id). |
config.rs |
The one config reader/validator. config::current() is the running app's config (one source of truth: panels read it, set_current replaces it when Settings saves). New settings: add the field + default + check in parse + a round-trip test, then a row on its page in features/settings/pages/. general.default_action = what Enter runs (actions::default_for), general.save_folder = Save's start folder, translate.live_interval_ms = the live layer's period, translate.source / target = the languages (auto = detect). [selection] = snap / shape, search at once / wait, Lens / AI / both; [look] = the active look: a preset (PRESETS, one table of Looks) or [look.custom]; config::look() reads it without cloning the config (the edge every frame, the widgets on every style), so a saved change applies at once. |
shared/app_language/ |
The app's own words (owner, 2026-11-11): strings.rs = the ONE string table, English source + Arabic (key: "English" | "Arabic";, S::key, t!(key)), mod.rs = Lang (En, Ar; rtl, endonym), the UI language per UI thread from general.app_language, else onboarding's general.language, else the OS's (of_config), fmt (isolated values in Arabic), count (Arabic plural forms); tests.rs = no key without both languages, no unused key, no word outside the table. Not translate::lang (the languages text is translated between). Recipes below: Add a string, Add a language, Make a screen direction-aware. |
shared/platform/capture/ |
One frozen RGBA frame of a monitor, or of every monitor at once (snip); one file per platform (monitors, grab, pointer). choose = the monitor holding most of an area (a scrolling capture's region), else the pointer's, else the primary. Circle to Search, translate and quick actions open on the MOUSE's monitor (owner, 2026-10-28; mouse_first: that monitor grabbed and handed over first, then, for Circle to Search, every other monitor together; a failed one is left out). Wayland: the portal's whole desktop, as before; on GNOME before 46 (its Screenshot portal asks every time, #157) screencast.rs instead: the ScreenCast portal with persist_mode = 2, asked once, the restore token in <data>/OpenCircle/screencast-token (never the config, never logged), each capture a restored session, ONE frame per monitor through GStreamer's pipewiresrc (dlopen, nothing linked), session closed at once; no GStreamer = the Screenshot portal. window_rect.rs: visible windows, topmost first (snip Window mode), and the foreground window. cursor.rs: the pointer drawn into a snip (snip.cursor). uia.rs: a window's controls (Windows UI Automation) for snapping. stitch.rs + scroll.rs: long capture BY HAND (N-73 point 5, 0.1.3-4; no auto-scroll, nothing injected): scroll::by_hand grabs only the area through frames::Frames (shared with live translate: Windows a Desktop Duplication, else win::grab_rect, the one GDI grab, as for a monitor: BitBlt into a DIB section, turned into RGBA on up to 4 cores; X11: the area through MIT-SHM, x11::Shm, at most 60 a second, else the monitor, cut; Wayland (#151): screencast::Cast, one restored ScreenCast session streaming the area's monitor only while the capture runs, newest BGRx frame cut to the area, no pacing; offered only with a v4+ ScreenCast portal and pipewiresrc, scroll::can_scroll) every 66 ms while there was input within 1 s (GetLastInputInfo) or the area changed, skips a frame equal to the last; stitch::Stitcher knows where the viewport is in the page (2026-11-03, the Snow Shot model rebuilt our way): it keeps the page so far with each row's signature (sigs) and the viewport's position in it (at); each frame is looked for in the PAGE around that position (up and down by up to 90 % of the body, over this pair's own body: fixed bands left out), and, when nothing there is trusted, in the whole page (anywhere: three evidence rows looked up row by row, the offsets they point at tried in full with the nearby ones as rivals; only a sure, nearly exact match over most of the frame, FAR_PCT). A frame inside what is captured only moves the position (Push::Moved: scrolled back up, or down again over it; never appended, so no repeats); rows are added only past the page's end; a frame not found changes nothing (Rejected), so after a jump the capture goes on as soon as a frame is found again anywhere in the page (no "lost" mode). Matching is on evidence rows (informative rows that changed at their spot against the last frame located: a sticky bar that shows up later matches nothing for free); on an equal mean the offset with clearly more evidence (5/4) wins; a step with an equally good rival RIVAL_GAP away is not trusted (an exact match only has exact rivals) (owner's README, 2026-11-02; a_smoothly_scrolled_readme_is_exact_at_every_scale models smooth scrolling at 1 / 1.5 / 2.5x, a late sticky bar and a side column). Sticky header/footer rows are kept once (bands: rows still but for a scrollbar thumb, spinner or caret count as fixed when they match in place better than scrolled; matching leaves such edge rows out; the band is the median of the last 5 moving pairs, and the page tail is repainted from each new frame's lower half, as Snow Shot, so a footer up to ~25 % lands once at the end even unrecognised; with only such narrow changes whole rows must match, so a spinner on a still page is no scroll; owner's chat prompt box, 2026-11-03). Memory: the image so far (page) + its signatures (~0.75 byte a pixel) + the last footer (a frame is freed once pushed). Stitcher::step = what the last push decided; OPENCIRCLE_LONG_LOG logs it per frame, OPENCIRCLE_LONG_DUMP=<folder> saves every frame stitched (field reports; off unless set). Replays: features/snip/capture/stitch/replay.rs replays frame sequences recorded on the VM (testdata/replay/: distinct rows + runs per frame) and checks them against the true page by a ruler the test page draws in the ignored scrollbar strip (record_replay makes a fixture from a dump; the test pages: docs/internal). 20,000 px limit; whole = the preview: the WHOLE image so far as a miniature (as iTop's; owner, 2026-11-02), min(max width / page width, max height / page height), scaled sharp by shrink.rs (exact area average, fractional edges weighted) in two streamed stages (the page at the max width, kept; that at the shown width, which narrows in 2 % steps, so it is rebuilt once per step: <= 3 ms at 20,000 px). |
features/text_reading/, features/translate/mt/ |
OCR (PP-OCRv5) and offline translation (OPUS-MT) on ONNX Runtime, only in the helper process opencircle ocr-worker. features/text_reading/ppocr.rs is the whole PP-OCR pipeline on ort (#61, no OCR library): detector (resize to 32 px steps, BGR ImageNet normalise, DB map -> contours -> min-area box -> Clipper unclip -> axis-aligned box) and recognizer (48 px high batch, CTC); its maths follow PaddleOCR / oar-ocr 0.10 step for step, so the same boxes and texts (features/text_reading/worker.rs: requests, the serve loop; models load on first use and stay). features/text_reading/session.rs: the app side (framed, request ids, one request at a time, timeout -> kill -> next call respawns). ocr::hold() keeps ONE warm helper while held: live mode (features/live_translate/screens/live_layer.rs) and an open overlay (App::helper) each hold one; the last drop kills it; ocr::keep_warm() (offline translation) holds it until 60 s unused. Unheld calls get a child per call. features/text_reading/system.rs: Windows OCR (Windows.Media.Ocr) in the app's process, for main mode's whole screen (ocr::route) and for translation, one-shot and live (pipeline::Real::recognize, system_reads). The decoder's output layer is folded once at load (session.disable_quant_qdq), else each decoding step rebuilt it; the models-v2 decoders hold it once, outside the merged decoder's two branches (scripts/lighten-mt-decoders.py). Model folders: <data>/OpenCircle/mt/OptimaMT-<source>-<target> (mt::DIR_PREFIX); mt::adopt_old_folders renames the pre-v0.1.7 opus-mt-* ones once at start (before any helper runs; Pair::dir uses an old one until a locked folder can move). |
features/translate/lang.rs |
The ONE language table (code, English and native name, script, RTL, OCR recognizer id): pickers, the AI prompt, RTL layout and recognizer choice read it. ocr::models::RECOGNIZERS = one pinned recognizer per script (en, latin, arabic, cyrillic, cjk; a source picks one, auto = English, then the other downloaded ones when it reads badly: ocr::Read); mt::PAIRS = one pinned OPUS-MT model per direction (Xenova's exports; a pair Xenova lacks: scripts/convert-mt-models.py, its release assets, a pair!(own, ...) entry, kept only if it beats the pivot through English on the matrix pages). lang::sure = one line's own language (script, word votes, then the whichlang detector for 3+ plain words). New language: a row (+ a recognizer / pair entry if it has one). |
app/shell.rs |
The iced daemon: overlay window state, capture on a thread, open / close (the multi-step Hiding), running actions, background (thread work → messages). |
features/circle/screens/overlay.rs |
The canvas over the frozen frame: dim, strokes, selection rules (classify: tap / scribble / drag / loop; settle = the selection and the stroke it keeps, a scribble's padded hull), corner handles (resize / move math), the Shift count badge, mouse / wheel / key events. View = the zoomed (1x–4x) and panned part of the frame: selections live in image px (the overlay at 1x), so crops are right at any zoom. The wheel zoom eases (features/circle/app/zoom.rs, #89): a notch sets a target, the drawn Opening::view moves there by the clock (View::lerp, motion::GLIDE Standard; a notch on the way retargets from where it is, the pointer's frame pixel kept under it; reduced motion = at once); while it eases or a zoomed view is panned the frame is drawn by Zoomed (Nearest, fractional; the plain dim folded in: the picture faded over black, one pass in the renderer), at rest by the image widget's crop with its usual filter. Unzoomed it is Frozen: the one frame image pixel for pixel (no tiles: its pixels are converted once, on the opening's first frame, and the zoom reuses them). Timing: frame_times::zoom_frame_times (by hand, release). Snap ([selection] style): snap turns the selection into a rounded box (Kind::Snap, stroke = two corners), morph draws the stroke becoming it (≤ 200 ms, the canvas asks for frames while it runs), brackets / bracket_at are its corners and grips (grip_at -> Grip: brackets or corner dots, then the edges (edge_at, resize_edge); a press inside moves the box unless it lands on read text, Alt makes any press inside move it (Event::Alt), arrows nudge it (1 px, Shift 10) and with Ctrl resize from the bottom-right (Event::Arrow, App::nudge; a focused field takes the arrows first); keep_inside keeps it on the screen). The dim is one drawing per 256 px tile; a box (Kind::Drag / Snap) is cut out of each tile as that tile sees it (seen_in: its rectangle clipped to the tile unless a rounded corner is in it), so a box moved or resized redraws only the tiles its edges cross, on every screen. Dims and colours come from the active look (theme::dims, theme::accent_of); select-text mode fills every word box and the picked ones. |
app/monitors.rs |
Circle to Search and Snip on every monitor (UI plan 41): the overlay is the starting (active) screen; each other monitor's frame lands after it (capture::mouse_first, Message::Screen) and opens a Screen, its own full-screen window (its one frozen frame image + dim + the selection, no bar / card / toast / hint; the edge glow follows the mouse (Glow: CursorEntered on a screen's window, Message::PointerOn; out of the screen left and into the new one at motion::WIDGET's pace, frames only while it fades); the bar stays where it opened; focus stays on the starting screen; opened and closed per opening, frames freed with the Opening; a late frame is dropped by its capture number). ONE unit for every screen: the starting screen's image px = desktop physical px moved to its origin and divided by its scale once (to_desktop / from_desktop), so a stroke crossing mixed-scale screens stays one line and one screen is unchanged; each window draws through its own View::mapped (view_of) and forwards its pointer events in the starting screen's px (on_screen_event; on Windows a press keeps the pointer in its window past the edge). Moves and resizes keep to Opening::desk (the box round every screen, keep_on); crop_of stitches a crop that reaches another screen from every frame it meets, pixel for pixel in desktop px (actions::stitch, gaps white), so Copy / Ask / Copy text get one image (text in reading order across). Text selection (I-beam, words) reads the starting screen only. |
shared/kit/motion.rs |
Every widget animation's timing, the new design's (core/motion.js): OPEN 210 ms, CLOSE 150, MORPH 190, GLIDE 200, DOCK 240, TOAST 200 (+ 8 px rise), the curves Out (expo), Standard, In, Ease; Shown = a thing opening/closing by a Pace (WIDGET, TOAST_PACE) from wherever it is; progress by the clock since a motion began; the OS's "show animations" off = instant. frames() is the frame clock (a thread, one tick per FRAME = 16 ms, never faster: the CPU renderer has no vsync, iced's own frames redrew as fast as a frame could be drawn). Cost rules: a whole window fades by its opacity (windows::fade, Windows layered alpha on a thread: nothing redrawn), never a dim or a group of widgets on the CPU; widgets inside the overlay move or scale and redraw only round themselves (the vendored renderer's damage, frame_times.rs tests the opening's). |
features/text_reading/app/word.rs |
Tap a word: OCR lines around the tap (recognize_in_child on a crop, on a thread; no models = no-op), split into words by character share (RTL lines from the right); a second tap on the line makes a range. A press-drag from the highlight or a Shift+click stretches it across lines in reading order (Picked::extend; past the lines read, OCR reads a full-width band, band / reread); one highlight rect per line. Copy copies the text, a line break between lines. |
features/circle/screens/bar/ |
The bottom bar (the new design's search bar, solid, on the kit): view.rs composes it (App::bottom_bar: kit::grip, the AI field kit::field::slots with its logo and "AI ↵" badge, the button::compact pills Search in browser · Copy text · Translate, then the round kit::icon_buttons from labs::bar), the reader's note beside it, its morph into the editing toolbar and the QR chip; geometry.rs is its size (pills lose their labels on narrow screens), docking anchors, Tab order and follow (while held it eases toward the pointer on the frame clock, ~50 ms, no jump per mouse event; let go, the glide to the nearest anchor starts where it is drawn). Its state is features/circle/app/bar.rs. Nothing is sent after a selection until a pill (or Enter / a key) is chosen, unless [selection] after = "search" (Settings > Auto action). |
app/keys.rs |
The one focus rule (#101): a focused text field (bar AI field, Ask panel input) takes every typed letter; the overlay's single-letter shortcuts (actions::for_key, E / A on a translation card) only get keys no field captured. keys::guard(field, f) wraps a field: Esc while it is focused leaves it and is captured (the global Esc subscription then sends Message::EscapeTaken, which never closes; an uncaptured Esc is Message::Escape = close), Ctrl+C with nothing selected in it (it wrote nothing to the clipboard) is Keyed::Copy = the overlay's copy; Ctrl+S is never a field's. New text field on the overlay: wrap it in guard. Tab / Shift+Tab (overlay::Event::Tab) walk bar::stops (Opening::bar_focus; iced buttons have no keyboard focus, so the focus is ours: the field gets the real text-input focus, the rest a soft accent look), Enter / Space press it (App::activate); a click resets it. A new bar button: add it to bar::stops order and App::bar_message. |
features/snip/annotate/ |
The Snip annotation editor (Annotator): Document (image, items, crop, undo stack; render flattens), one file per tool. The toolbar is grouped (owner approved, 2026-11-02; SNIP_TOOLBAR_SPEC): Group = Select · Shapes (rectangle, ellipse, line, arrow) · Draw (pen, highlighter) · Text (text, callout, numbered steps) · Hide (blur, redact, spotlight, magnify); ToolInfo::group, and ToolInfo::slot = the tool a variant is an option of (arrow with a label = Arrow's "Label", Label = Text's "Background", Pointer = Steps' "Pointer"). Each group button shows its last tool (Annotator::last, remembered as [editor] group_tools); its first click picks it; a click on the active group opens its panel (Menu::Options(Group), toolbar::options_panel, one design for all: the group's tools (a pick keeps the panel open), the tool's name and key, then its options: Size (presets + slider: Annotator::stroke, [editor] stroke), Outline, Fill (rectangle, ellipse only: fills_inside; dimmed for lines and arrows), Text: Font size, Bold, Background; Steps: size, Pointer, Legend; Blur: Brush (Auto + presets), Pixel size, Line help). Undo's click undoes; right after an undo (Annotator::undid) it opens its panel (Menu::Undo: Undo, Redo, "2 of 3 steps"). More (Menu::More, toolbar::more_rows, 268 px / 304 Arabic, option_list::action_menu): Copy text, Ask AI, Translate (0.1.7, SNIP_MORE_SPEC: actions::snip_more holds the decisions: each row's shortcut caps from the user's quick actions, why a row is off and the foot, Hidden = what Blur / Redact / Spotlight hide, mask / visible keep it out of what is read; the work is main mode's: actions::text, App::open_chat with the annotated Output::AskAi(Crop), translate::Session on the masked clean capture, its result pasted into the document image and Show original restoring it, features/snip/app/snip_more.rs; the area is read once when More opens, Annotator::more carries the state to the menu; the same rows answer the quick-action keys while Snip has an area, App::more_row_of), a hairline, then Long capture, Pin, Live pin (Labs Pins), Share, the colour picker, the ruler; arrows walk it (Message::MenuStep, Home / End MenuEdge; dimmed rows are skipped), Enter runs a row. A long capture running: Finish::CopyText / AskAi finish it first, Translate is off. legend.rs: the steps' notes in a box (free corner, else a band under the image). blur.rs: the blur brush = a fine pixel mosaic (owner, 2026-10-31: iTop's look, softer, smaller cells): image-anchored cells (Pixel size Fine / Medium / Coarse = 6 / 9 / 12 display px, default Fine, Width::cell, Shape::Blur::cell; nothing finer: 4 px failed the candidate-scoring test on Windows), irreversible underneath (Depix, candidate scoring; per-block means still ranked the true text above chance on Windows): the source is read ONCE per stroke: its mean tone under the footprint and one tint (blur::colours: background = the most common exact colour under the footprint, ink = per channel the most extreme value away from it among the 2 % furthest in tone: neither tracks how much ink there is; blur::snapped_tint: the chroma of their middle snapped to 48, none for grey text and ClearType fringes on it; blur::tint: + a secret per-stroke jitter of ±8 after the snap, spread kept within 255); the stroke's tone + a secret offset (±32), snapped to 16 with a secret dither, kept so far inside 0..=255 that no noise clips or folds; the mosaic is drawn from secrets only: coarse blocks (one brush tall on the stroke's band, 2.5 wide) = that tone + a secret offset (±20); each fine cell = its tone interpolated between the blocks + a secret jitter (±14) (OS-random seed, getrandom; Shape::Blur::seed), in grey + the stroke's tint, the same on every cell (no colour noise, no cast); then two quarter-cell box passes; the footprint is a hard-edged flat band size tall with square ends (no half-covered rim pixel shows its source); Redact stays solid. lines.rs: the blur brush's Auto size (text lines from glyph edges, no OCR; nothing drawn; lines set so tight they touch are split at their dense x-height cores, each band taking all the sparse rows up to its neighbours' cores: they overlap in the gap; lines::under picks the band whose middle is nearest); Auto puts the stroke on its line's middle; stroke = the line + a margin of max(2 image px, 2 display px, 15 % of the height) above and below (all of the ink, accents and tails too), never past the free rows to a neighbouring line's core (Band::room, Band::stroke); line help (blur::follow): a stroke holds the height it started at until a clear move up or down (1.5 brushes), Shift frees it. style.rs: presets (keys 1-9) and copy/paste style. Remembered across sessions ([editor], Annotator::remembered / restored): the last tool (never Crop), colour, shared size, Text size, outline, fill, blur size (missing = Auto), line help; each written only once changed (the default file stays frozen); any non-pointer message that changes them updates LAST in memory at once and one debounced write (500 ms, a worker thread, config::update). dragout.rs: OS drag of the flattened PNG (Windows only; temp file deleted with the editor/pin). area.rs: Snip's live area (N-73): after the pick the document is the whole frozen monitor and its crop is the area (Annotator::movable, SnipToolbar::live; the canvas sits at the monitor's origin, so window px / zoom = image px): 8 handles + edges resize it in every tool (the crop only: cut or extended from the frame, the drawing never scales), a press on empty space with Select (the starting tool) moves it with every item, arrows move 1 px (Shift 10, Ctrl resizes from the right / bottom edge, Ctrl+Alt from the left / top), each one undoable Edit::Area; The host keeps the overlay's selection on it and docks the toolbar with bar::dock (under, above, inside the top / bottom edge; the screen with the most room; clear of the dragged handle). select.rs: an item moves ONLY with Ctrl+press (Message::PressMove, by bounds, any tool; the move cursor shows only with Ctrl held) or the Select tool (by bounds); a drawing tool's plain drag always draws, even over an item (a click on one of its own text items types into it, Annotator::grabbed; a drag from there draws); no selection frame: only the item's own handles (select::handles: an arrow's ends + bend, a callout's bubble corners + tip, else corners; pen, highlighter and blur none), drawn as the kit's soft area handles in the look's colour, working in every tool. The editor draws nothing in the UI's name: its views are features/snip/screens/snip_toolbar/{toolbar,canvas}.rs (kit parts only); input.rs = what the pointer and keys mean (Annotator::key, cursor), chrome.rs = what the canvas draws over the image (crop preview, handles, caret) as plain numbers. Toolbar popovers go to the host as a full-screen floating layer (toolbar::view_at); toolbar::place_popover is the one placement (under the button, above the toolbar when there is no room, clamped to the screen). The Text button's options hold the text options (size, font, bold, backdrop: text::Style on each text). Outputs the host wires: CopyWithText (actions::copy::with_text). Annotation text in sans is the bundled Inter (Arabic: the bundled Noto Sans Arabic), the same on every PC. Goldens: every tool drawn and selected, Sapphire + Daylight, Latin + Arabic for the text tools (features/snip/screens/snip_toolbar/canvas.rs, tests/fixtures/editor/). |
features/snip/screens/snip_toolbar/ |
mod.rs (SnipToolbar), toolbar.rs, canvas.rs, picker.rs. SnipToolbar::fitted: a capture of its own (a stitched long capture, a recent one, a toast's across screens) opens in Snip's picked state: the live area is its whole image (Annotator::own_image: always painted, never bare), shown whole on the work area (scaled down, never past 1:1; a page taller than the screen shows smaller, every handle in reach), Snip's toolbar docked to it. |
features/circle/app/quick.rs |
Quick actions: id → what runs (registry action, copy_text, ai_explain), target → area (full_screen, circle, last_region per monitor; window is snip-only and counts as circle elsewhere). |
features/translate/screens/pill/ |
Translate in place (mod.rs = the session and its work; view.rs = the language pill and the result card from kit parts) (Alt+Shift+T = full screen; R in the bar = the selection): Session runs translate::pipeline::translate_progressively on a thread with actions::translate::deps(): top of the screen first, Deps::batch sentences per call (offline: mt::BATCH; a cloud model: one call), each part shown as it is ready (Msg::Partial, at most every 300 ms, drawn from the original like the whole page, on a drawer thread while the next call runs, so only the whole page's render adds to the total), then the whole page (an error leaves the original); one log line per translate with the stage times, a tap on a block = word card (Explain = one streamed AI call with the block's text + crop; A = Ask AI panel with that chat). Missing OCR models: the download card (screens/model_download.rs). The prompts (download question, progress, error) are short cards, as tall as their text (kit::panel_frame::short), never a full-height slab; only the word card is tall. translate::render keeps translations from colliding (separate: two redraws whose glyphs overlap each give up half the overlap and are fitted again, or the block stays as it was; Drawn::ink = the glyph boxes, for tests). |
live_core/ |
The live translation core (owner, 2026-11-15; design: live-approach.md 5-6); live translate runs on it (features/live_translate/live.rs = the engines, screens/live_layer.rs = the loop). Live::on_frame = the watch, every new frame: each tracked region's text area and ring (Config::ring_px around it) as gray cells (Config::scale px, 4 = 1/4 scale; pixels::cell); a read region whose text changed (mean diff > change, or 2+ cells over twice that) or whose ring moved (> ring of its cells) leaves the list and its patch is hidden in that same call, and the next discover runs at once; changing text is read once settled (settle_frames still) or after settle_max, only where the ring is held (text on a moving background is never read or patched); one read batch in flight (settled, newest, smallest first); the text-signature cache (cache_signatures, exact cell hash -> text) and the translation cache (cache_texts) skip OCR / MT for a line seen before (cache::Lru); a patch is drawn ONCE (Layer::show) and only faded in (Layer::alpha, fade_in, ease-out); where the capture contains our layer (X11, Wayland) "shows our patch" counts as unchanged. The discover step (discover_every, one Job::Detect in flight): 8x8-cell tile hashes of the frame with the read regions masked -> changed clusters -> areas; detected boxes become regions (a still-changing one takes its newest box; boxes in an area retired after the detect was asked are dropped). Live::complete drops a result whose region changed since (the caches still learn it). Back-off: report_burst (3 bursts ~2x the first minute's mean -> true once; discover 1 Hz) and report_cpu (> 85 % for 2 s pauses discover until < 70 %); the watch never slows. The host plugs in Detector / Reader / Translator (via Job::run), Painter, Layer, owns the threads, the capture and the clock (Frame::at). Tests: synthetic frames + a replay of the harness' talk clip truth (tests/fixtures/live_core/talk.truth, 1/4 scale): 0 stale frames, 0 redraws; bench_on_frame_10_regions_1080p (ignored). |
features/live_translate/screens/live_layer.rs |
Live translate (Alt+Shift+L, tray item): a monitor-sized, always-on-top window (X11: override-redirect, so a focused full-screen game never covers it) made click-through by live::prepare_layer, see-through except the patches (theme::LAYER_CLEAR). The session (0.3.0 step 3) runs the live core on two below-normal-priority threads (gently_here): the FRAME thread takes every frame the monitor shows (capture::frames::Frames; none new = the last frame again every 16 ms, so still text settles), blanks what is never read (our edge taken out by on_screen where the frame shows the screen, controller, our own windows, outside the focused window's page) and calls Live::on_frame (a changed patch is hidden in that frame) and Live::complete for finished jobs; the WORK thread runs the jobs one at a time, translations first, then reads, then detects, on live.rs's engines: Detect (the changed areas stacked into ONE OCR call, grouped into blocks = regions), Read (reuses the detect's lines while the crop still looks the same, else one stacked OCR call), Translate (translate_blocks: the shared cache, the glossary), Paint (translate::render on a window round the block; only the changed pixels are opaque). The layer gets Msg::Show once per patch and Msg::Hide (logged live: shown ID at X,Y WxH / live: hidden ID: the harness times them; live stats every 10 s). Back-off: burst times and the system CPU (sys::cpu::Load) go to the core. Language change: everything read again; an edited glossary: forget_translations. translate.live_interval_ms is still read but unused (its row hidden). While the session is away (live::away: WTS lock / switch / disconnect, display off, Windows) or paused nothing is captured and the layer clears. Off = stop flag + window closed. Wayland / no layer: one-shot instead. Draw once (0.3.0 step 4): the patches are retained slots, a stack layer each (an empty slot stays, so no other patch moves or redraws; the next patch takes it): a new patch, a fade step (Msg::Alpha, the core's 120 ms fade_in) or a removal redraws only that patch's rectangle (only_a_patch_that_changes_is_redrawn, via shot::damage). Where the layer blends (X11 + compositor, Layer::blends) a patch fades by its opacity and the edge is the Quiet glow on the layer (its fade-in: Msg::EdgeFade steps); where it doesn't, a patch fades as a blend with the pixels it covers (taken from the frame it is shown on, Over) and the edge is the glow's own alpha_window (Windows) or a solid line with the layer cut to the line and its patches (X11 without a compositor, Layer::cut). Stop fades the layer out where windows fade (Windows); the glow window fades out on its own thread. OPENCIRCLE_TEST_CAPTURABLE (test builds / hooks on) keeps the layer and the controller in captures (recordings show the patches). Also opens the mini-controller (features/live_translate/screens/live/controller.rs, kit parts only: grip, language picker, Pause, Hide = dot, Stop; draggable, takes clicks, live::prepare_controller excludes it from capture on Windows, X11 captures get its spot blanked). |
features/snip/screens/pick.rs |
Snip mode (out of Labs since 0.1.3 with its editor and screen tools; opencircle run snip, tray; ONE flow (owner, 2026-10-31): Print Screen, the main bar's Snip / E / run edit (over the frame already frozen, App::snip_here: a selection starts picked), tray, quick action and CLI all run it; Settings shows one Snip row and the config has one snip quick action (schema 9 dropped the old window / full_screen entries); `opencircle run snip --target window |
features/ask_ai/screens/ai_chat/ |
The AI chat (Ask AI; features/ask_ai/app/ai_chat.rs opens and drives it): mod.rs = state and work, view.rs = what each card shows, from kit parts only, inside the one result card frame (kit::panel_frame::chat_frame, the design's .as-card: widget surface, radius 18, accent glyph + title + model pill, ×, body, actions 18 px under it; solid, no shadow until glass). screens::ai_chat::card adds the × with its tooltip; translate and song use it too. Geometry (kit::panel_frame): place = 40 % of the screen wide (at least 420 px) on the side away from the selection, at the bottom on narrow or portrait screens, or where the user left it this run; short for prompts; free = the screen part the card leaves, where the bar, chips, popup and pills go; the inner edge resizes it (a grip shows on hover, double-click resets). The AI chat docks at a side; it pins itself after a follow-up (chat.stays_open: or at once) or by its header pin, and the App then keeps it (app/ai_chat.rs Resident, never more than one). The chat is its own floating window from its first frame (app/ai_chat.rs ChatWindow, platform::windows::floating, out of captures; Windows / X11, App::own_window): kept above the overlay (windows::keep_above: the overlay owns it / it is the overlay's transient), the keyboard left with the overlay until its input is clicked, placed where the overlay docks it, hidden in Snip, never re-created when the overlay opens or closes; App::sync_chat_window (after every message) opens, places, hides and closes it. Wayland: drawn on the overlay while open, its own window only once the overlay closes. With the overlay closed the OS drags it, then it docks; the next capture leaves it where it is and asks into it with its crop (Panel::ask_about); only its pin closes it. Its requests carry the last 20 messages + one provider-written summary of older ones (ask::WINDOW, REFRESH). The composer is kit::text_area (the design's box: the attached screen's chip::attached while a picture goes with the next message (Chat::takes), the field, then button::switch Include screen and Send; no privacy line; web search's Auto / On / Off comes with AI online). The logo opens its drawer (History from store::chats: search over titles and text, card::chat per chat with its star (favourites first, kept longest) and crop size, Del, Local on this PC / Clear all; Settings: stays open, provider picker from Settings' list, safety-model warning, Open AI & model settings). |
shared/store/ |
The app's one database, opencircle.db in the local data dir (SQLite compiled in, rusqlite bundled): growing records, one table set per feature in a file of its own. mod.rs = open (WAL, PRAGMA user_version migrations from MIGRATIONS), the one writer lock, path (tests: none unless a test sets one). chats.rs = saved AI chats (chats, messages): text only, never image bytes (had_image marker), newest 100, while chat.keep_history (off = all rows deleted + VACUUM). The config stays in config.toml. |
shared/history/ |
What the app remembers on this PC, each opt-in. mod.rs = Settings > History's view of it (Kind: recent captures, AI chats; tidy clears the kinds asked, then counts each where it lives: the recent folder, store::chats; on a thread). |
features/circle/screens/edge.rs |
The screen edge per mode (Mode = overlay, live, snip): the active look's design Active Look (kit::looks, via theme::kit_look from the stored id; the user's own colours = a Glow) drawn by kind: Glow = the soft inset glow (inset 0 0 22px c1, inset 0 0 54px c2, radius 14); Horizon = that glow on the top and bottom only, fading out to the left and right ends; Hud = the glow + four 30 px corner brackets 12 px in (2.5 px c1, radius 8, 8 px c2 shadow; static); Bezel = 1.5 px c1 line + 8 px c2 band + 28 px c1 glow. No moving colours (owner 2026-10-27), no breathing (owner 2026-11-12). Strips (2 for Horizon, else 4) made once per size and look on the first frame; later frames redraw nothing. The only motion is the overlay window's own fade-in. Live translate: the Quiet glow (owner, 2026-11-14, option B): a Glow whatever the look's kind, at 1080p c1 in a 14 px blur at 0.36 / 0.42 of its alpha and c2 in a 34 px blur at 0.20 / 0.26 (reach 64 px), scaled with the monitor's HEIGHT (h / 1080), not its DPI scale; live makes it once per session as strips (for its own window) plus an on_screen::Drawn (taken out of our captures); a layer that can't blend (X11 without a compositor) gets a thin solid line in c1 instead (keyed, kept off the Windows key; live_line = its four strips, what the layer is cut to). Config animate / activation_glow / thickness (glow only) are kept but unused. paint = a look's edge on a picture (tests). Goldens per kind: tests/fixtures/edge-{default,hud,bezel,horizon}-1080p.png; Live: edge-live-{sapphire,spectrum}-{1080,1440}p.png + edge-live-fade.png (OPENCIRCLE_UPDATE_GOLDEN=1 rewrites them). |
shared/on_screen.rs |
What we lay over other apps that captures still show (Live's edge: Windows can't keep an alpha window out of captures; X11 has no exclusion): show(Drawn) registers it until the returned OnScreen drops; take_out / take_out_of work the blended pixels back out (solid ones blanked, reported) of every grab of ours: Live's frames (live_layer::blank), Circle to Search (app/capture.rs), Snip (snip/capture/frozen.rs). |
shared/platform/alpha_window.rs |
A click-through, topmost window showing one picture with per-pixel alpha (Windows UpdateLayeredWindow, its own thread): drawn once, faded in by its constant alpha (motion::WIDGET), faded out and destroyed when the AlphaWindow drops; nothing elsewhere. Live's edge glow on Windows (live_layer, just under the colour-keyed layer). Part of the UI (arch_tests). |
features/song/ |
Song search (opt-in, the user's own key): listen records 10 s of mono 12 kHz while listening only (capture_linux.rs: the default sink's monitor over the PulseAudio protocol, pure Rust, PipeWire too; capture_windows.rs: WASAPI loopback / mic via cpal, Downmix to mono 12 kHz), identify sends the clip as WAV to the service (audd.rs: multipart request, JSON parsing, error mapping; a second service = one more file + a Service variant), cover fetches the PNG cover, history.rs (local, off by default). The key is secrets::by_name (song-key-audd); key_known caches whether one is saved (Settings updates it), so the overlay's music button shows only then. features/song/screens/song/ = the "Listening… N s" pill (Cancel) and the result card (the one result card frame, kit parts only). |
features/translate/screens/language_picker.rs |
The compact language picker (source → target openers, list with search, recent first; kit::option_list rows, a badge for what needs AI), shared by the live controller and the one-shot translate pill; picks last for the session. |
shared/kit/ |
The one UI kit (0.1.2 plan): tokens.rs (radii, spacing, sizes, type Roles, fixed colours), themes.rs (the design's 12 themes as data, current/set/resolve; the setup follows the OS: Sapphire dark, Daylight light), looks.rs (the 10 Active Looks + custom), motion.rs, text.rs (fonts, ui_font, MONO, text(Role, s)), icon.rs (Icon), and the controls surface, button (Elevated / Accent / Success / Danger / Quiet), segmented (+ boolean; both as wide as the settings control column, inline / inline_boolean as wide as their labels), field, chip (+ tag, badge, pill, status, dot, done), divider, progress, keycap (+ empty), shortcut_field (size::CONTROL_COLUMN x 36, one keycap per key, Rest / Recording / Conflict), dropdown (kit-built: an opener and a menu of option_list rows in scroll; no iced pick list), slider, colour (swatch + picker), field::input (.oc-input), header (regular 40 px with caption buttons, compact; frame / with_edges = a normal window's header and resize strips), tooltip (hint(content, label, Why, side): a visible tooltip only for an icon-only, cut or shortcut-carrying control, drawn as surface::hint; tip = the name alone; tests_support = the policy test), loupe (snip's magnifier canvas, kept off a dragged area), area (Snip's soft outline + handles in the active look's pair, passed in), key_hint (a hint pill with keycaps), chip::readout / chip::info (Snip's size readout, hover info chip), button::tool (a toolbar's icon-only Copy / Save; themes::on = the readable glyph on an accent), button::toggle (an on / off switch: the toolbar panels), segmented::presets (S / M / L dots or letters), slider::bare (a rail alone), option_list::action (a menu row with its glyph and key: More), surface::panel (a toolbar's panel, size::PANEL), chip::size_handle (Snip's size chip, the drag-out handle), grip::mover (the grip with the move cursor), button::dot (a control minimised to a dot), logo (+ window_icon, png_handle), sidebar (168 px, one gliding highlight), setting_row (row / block; every row's control sits in one column, size::CONTROL_COLUMN wide at the right, rows at least size::ROW_MIN tall: the settings layout test checks every page), card (info, theme_card, look_card, chat = a History card, grid), text_area (the chat composer box), error_card (an AI error: a red icon, the headline, the provider's message clamped to two lines with Show details, one fix button + Retry; screens map AiError::headline / detail / fix through ai_chat::ai_error), chip::attached, button::switch (an on / off pill), text::cut (truncate with …), focus (keyboard focus, v0.1.8: Stop round a control, press for a button, scope = a window's Tab / Shift+Tab walk in tree order = reading order (RTL too: dir::row keeps its children in reading order), wrapping, the focused control scrolled into view; Enter / Space press, arrows step a segmented track / slider / closed dropdown (an open one: up / down walk its rows, Esc / Tab close it); the focused control's soft background (shade: the theme's accent_soft, on a filled call to action its text colour at that strength, Stop::on_fill; never a ring or border) only while the keyboard leads: any mouse press unfocuses, a new scope (a reopened window) starts clean; text fields keep iced's own focus and join the walk), scroll (the one scroll area and scrollbar; across for code blocks). testing/: shot, golden::check (golden images, OPENCIRCLE_UPDATE_GOLDEN=1), gallery (one sheet per control). Depends only on iced, std and itself; app/arch_tests.rs enforces it and the screens' no-styling rule (LEGACY is empty since step 38: no screen styles in place). |
shared/theme.rs |
The glue between the config and the kit (no colours of its own beyond the looks' table): apply(Theme) = the Settings choice, set_os(Mode) = what the OS reports (System follows it), preview; both set kit::themes from the [appearance] picks (kit_theme). Active looks: colours(ColourSet) = each preset's edge glow and accent, edge_glow / accent_of / dims / bracket, kit_look = the design look a stored one shows. |
shared/net.rs |
The ONE ureq agent builder: net::agent(Policy) with a named policy per caller (AI, MODELS, UPDATE, SONG, COVER); a test pins each caller's timeouts and another forbids building agents anywhere else. net::dropped tells a connection that broke before any answer (reset, EOF) from no connection; every AI request goes out through ai::send, which resends such a drop twice on a new agent (never once the answer streams). |
shared/platform/sys/ |
OS plumbing: open.rs (links, mailto, Settings pages: one launcher, no shell, web_host = the one URL check; Linux via the portal), serve_once.rs (a page for the browser served once from 127.0.0.1: random port, secret path, one GET, memory only; the Lens hand-off) and spawn.rs (spawn_detached). |
shared/log.rs, shared/diagnostics.rs |
log! = eprintln! plus the rotating file <data_local>/OpenCircle/logs/opencircle.log (1 MB x 3; OPENCIRCLE_LOG_MAX_BYTES shrinks it for tests); every line passes log::redact (keys, Bearer, key=, JWTs, home folder -> ~). Use crate::log! for anything printed, and never log user text (OCR, translations, prompts, clipboard). install_panic_hook (main) writes crash-<time>.txt (5 kept; hidden test hook: env OPENCIRCLE_TEST_CRASH). diagnostics::report (Settings > About > Copy diagnostics, redacted) and issue_url (Report a problem: version + OS only). |
shared/platform/tray.rs |
Tray icon and its menu's entries (entries, one list: Circle to Search, Translate screen, Labs rows only when on, Settings…, Quit; Entry::trigger = what each runs, Entry::shortcut = its hint). Windows: no shell menu; a right-click sends Trigger::TrayMenu(icon rect) and ui::windows opens our popup (screens/tray_menu.rs, kit::option_list::menu/item) through floating, placed by place (off the taskbar on any edge, inside the icon monitor's work area, physical px); arrows/Enter/Esc, closes on focus loss; a capturing pick runs after the fade-out + SETTLE. Linux: the desktop's menu (AppIndicator), same rows. Without libayatana-appindicator (Linux) it logs one line and the app runs on shortcut / CLI. Windows icon identity: a GUID hashed from the exe path (guid_for; Windows refuses a GUID from any other path), so a start first deletes the ghost a force-killed run left under it (the shell refuses to add a GUID a ghost holds), then adds; refused → plain icon (add_with_fallback). "Shown" = Shell_NotifyIconGetRect succeeds: S_FALSE (icon in the overflow flyout) counts, unlike tray-icon's rect(). |
app/windows.rs |
The normal windows beside the overlay: Settings and first-run Onboarding (one of each, a second request focuses it), their close handling, the OS-theme feed, and apply(cfg) after a save. Also the pinned images (editor Pin / Ctrl+P): any number of borderless always-on-top windows, each owning its image (drag, scroll = zoom, hover bar Drag (Windows) / Copy / Save / Close, Esc or double-click closes); a live pin (Labs Pins, Windows: Snip toolbar Live pin or the live_pin quick action, at most 4) is the same window fed by capture::live (Windows Graphics Capture of one window, the crop kept relative to its client area, read at most every 100 ms and once a second while unchanged), with Opacity and Click-through on its hover bar (back: the tray menu's "Make pins clickable", shown only then), and the Settings side effects (folder picker, project link). Every window opens through normal (here) / floating / screen / setup_window (shared/platform/windows.rs, the OS side of windows; foreground gives a shown overlay the keyboard, joining the foreground thread's input only when Windows refuses SetForegroundWindow, e.g. to a hidden foreground window), all via its open (a test forbids window::open elsewhere; shared/platform/ imports none of the UI, arch_tests::platform_is_isolated; the icon is handed over once by ui::run, set_icon): no OS title bar, our icon, and on Windows platform/shape.rs's no_caption (winit leaves its undecorated windows a hidden caption that DefWindowProc paints, the classic "OpenCircle" strip, at every (de)activation where DWM doesn't draw the frame; WM_NCACTIVATE gets lParam -1). A window opened with skip_taskbar (the overlay, every popup) is a tool window for good (shape::no_taskbar: winit rewrites the extended style with WS_EX_APPWINDOW on every show, hide and full-screen change, so its own skip came undone). windows::clear_now makes a window clear synchronously on the UI thread (a Task lands after the next frame): the overlay's close clears it before its hide steps draw the empty view and leave full-screen. |
features/settings/, features/onboarding/ |
The two screens as self-contained components (State, update returning an Outcome, view). Onboarding: flow.rs (State, Message, update, the STEPS list: Your language (the language picker list, always open; sets translate.target and general.language, names the model the first translation downloads), Welcome, Screenshots on Wayland only, Connect AI, Look, Done; a new step = one entry + one file in steps/), the design's fixed 680x525 window (nothing scrolls), its own header, the step track (kit::segmented::spread, the thumb glides; the step switches at once, like Settings pages: frame_times::an_onboarding_step_change_redraws_only_the_track), footer Back (off on step 1) / Skip (AI step) / Next / Finish. It embeds a Settings State (auto-save off) and shows Settings' own rows (settings::rows: the same functions the pages use, one source of truth); Finish writes that draft through config::update_at, or names the problem to fix. Settings: state.rs (State, Message, update, Outcome, the key field), window.rs (the shell: kit::header::regular with the auto-save pill (Auto-save active / Saving… / Saved / what is wrong), kit::sidebar gliding on GLIDE; the page switches at once (the design's rise redrew the whole window each frame on the CPU renderer: it returns with the GPU renderer, 0.1.3; frame_times::a_settings_page_switch_redraws_only_the_sidebar_glide); header buttons come back as Message::Caption, which app/windows.rs turns into the window's own moves), pages/mod.rs (PAGES: one entry per page; a page with lab is listed only while that Labs switch is on), one file per page (General, Appearance with custom.rs for the custom look's rows, Look & behaviour, AI, Text reading (Windows only), Translate, Shortcuts, Snip and Song search (Labs), Privacy, About, Labs), all on the kit; KeyField::view (in pages/ai.rs) is the key row onboarding shows too. Appearance: reduced motion (the OS's, shown), the 12 theme cards (no OS mode or logo colour rows, owner 2026-10-28): a card is its mode's [appearance] pick and sets theme to its mode (a config that never picked one keeps system; [appearance].logo stays as stored), and re-themes at once through theme::preview (before the write); then the 10 look cards + Custom (appearance::picks: a card writes the stored value config v4 keeps, aurora = Prism, mono = Frost, borealis = Aurora Borealis, the shown card keeps calm) and, for Custom, every part of the look. Look & behaviour: the selection rows and a button to Appearance; the text reader is on Text reading. kit::text::width shapes as the text widget does (ASCII unkerned), so a measured label never wraps. |
features/circle/actions/mod.rs |
The action registry (ACTIONS), Run (finish, Ask AI, Search in browser, Snip, Translate), crop, encode_png, write_png. One file per action: search_in_browser/ (mod.rs = the action and the page's minimum life, page.rs = the hand-off page the browser posts to Lens, served once by sys::serve_once), ask.rs (setup, Chat, streaming, PRESETS = the suggested questions for every provider), text.rs (Copy text: consent check, OCR, line joining; run text = copy the area's text, no card), translate.rs (the pipeline's deps from config + keyring), copy.rs (scaled to snip.max_edge, the picture only; one clipboard for the app's life, used off the UI thread), save.rs (fit_long_edge + encode: PNG / JPEG), share.rs (Snip's Share: the flattened image as a temp PNG (DragFile, gone with the editor, a grace after a target took it) to Windows' share sheet (IDataTransferManagerInterop on the active window); a picked target closes the snip like a drop; not in ACTIONS: the toolbar is its only entry; Linux: no button yet). Not actions: entities.rs (links, emails as the chip beside a text selection; click only) and qr.rs (QR decode + black-capture check, run off the UI thread when a selection is made; feeds the bar's QR chip and the "protected" pill). |
shared/update/ |
Auto-update ([update] auto; unset = not asked, off) and the update experience (owner, 2026-11-10). mod.rs: the thread (first check 45 s after start, then every 12 h, or Settings' Check now; one update offered per run: offer(), checked() for Settings and the tray), prepare (a portable exe / AppImage: right after the download, swap, --version smoke test, a quiet marker: the new version is what starts next, whatever ends this run), restart(staged, Moment) (Restart now or a long lock: relaunch with updated, exit; a setup's copy only on the button), confirm at the new process's boot (What's new after Restart now, the small "Updated" pill after a quiet install; just_updated = a second start then opens nothing) / roll_back if it can't start. flow.rs: the pure decisions (installs_at per install kind and moment, the pills' Pill life: waits while away, 30 s, Lock = locked a minute, Settings' status line). release.rs: latest release JSON (ETag, rate limit), is_newer, pick = the asset per install kind (Windows *_x64-portable.exe; a copy our MSI installed (Install::Setup, by_setup: this exe's folder = the InstallLocation of the MSI's Apps & features entry) takes OpenCircle-Setup-<ver>-x64.exe, same signed checksums, and installs only on Restart now: restart runs the verified setup elevated with /quiet /launch (one UAC prompt; declined = nothing changed, the file stays staged for another try) and exits; the setup quits the old copy, installs, starts the new one, whose confirm shows What's new (a marker of another version = the install failed: nothing shown); AppImage; deb / rpm / source = Event::Manual, "Get it" = the release page), stage = download + verify into a fresh private dir (<local data>/opencircle/update, never shared temp; the install re-hashes its copy). verify.rs: minisign over SHA256SUMS.txt with RELEASE_PUBLIC_KEY (empty = refuse all), then SHA-256 (scripts/install.sh, the Linux one-command install, repeats this check in shell with the same key; tests/install_script.rs keeps the two keys equal). swap.rs: replace keeping <file>.old, restore, the marker (update.json in the local data dir; quiet = the small pill). notes.rs: release notes → summary, at most 6 Highlights, Fixes / Upgrade notes (by ## name), inline bold / code / short links. UI: app/updates.rs (the App's side: pill, tray dot, lock install, Restart now), app/screens/update_pill.rs (ready / Updating / Updated pills above the tray), app/screens/update_card.rs (What's new, kit::panel_frame::frame), the tray row (platform::tray::Entry::Update, show_update), Settings > General's Updates row. The update widgets show in captures (windows::floating_in_captures). |
shared/setup/, app/screens/setup/ |
Our Windows setup (#55), OpenCircle-Setup-<ver>-x64.exe = this program built with OPENCIRCLE_SETUP_MSI=<the MSI> (build.rs embeds it, cfg setup_payload; setup::payload makes main run the setup instead of the app). shared/setup/mod.rs: check_folder (the one install-folder validator), the default folder, quit_running_app, forget_user_data (--forget-user-data, run by the MSI's uninstall: asks, then removes the config / local data folders and the keyring keys). launch (the finish step's Launch, off the UI thread: quits a still-running old copy first, starts the installed exe detached as the user, waits until it answers). uninstall_ui (--uninstall-ui {ProductCode}, our Apps & features entry's UninstallString: copies the exe to a temp folder, the copy shows the uninstall window and deletes its folder after it exits; the MSI's own ARP entry is hidden, ARPSYSTEMCOMPONENT). shared/setup/msi.rs: Package (the MSI unpacked into a fresh temp folder, held open read-only, deleted on exit), installed (the MSI's upgrade family: version, folder, same package = repair), install (`MsiSetInternalUI(NONE |
vendor/iced_tiny_skia/ |
iced's CPU renderer 0.14.1 with OpenCircle patches ([patch.crates-io], each marked OpenCircle patch in the source): drawn_bounds in src/layer.rs damages where a centred / right-aligned text is really drawn (#53); boxes_moved there: two drawings of as many primitives damage only the primitives that changed, and a fill of rectangles (the dim's tiles, which draw a tile with no hole the same even-odd way) only the strips its rectangles gained or lost (a snip area resized or moved: 26 % of the screen a frame -> 3 %); Layer::frame_damage counts a layer that came or went only where it draws (#23); engine::adjust_clip_mask touches only the pixels that change (and Renderer::draw sets a layer's clip back once after its groups, not after each: the dim's tiles cost two window-sized fills each, ~20 ms of a 3440x1440 first frame; MASK_PIXELS counts, for the tests) and pixel_rect is the one rule for the mask, the damage's clearing and raster::Pipeline::blit, which copies / blends an image that lands pixel for pixel (placed where draw puts it, its position truncated, so the frozen frame and edge strips set a quarter pixel in are blitted too, #134) instead of tiny-skia's pipeline (#23; PIPELINE_PIXELS counts what still goes through it, for the tests); RGBA images are converted straight from their bytes, in one pass split between the cores (#23); window/compositor.rs presents only the redrawn rectangles on Windows (#23), and on X11 while CHANGES_ONLY is set (the live layer on a composited X11: the X server keeps every window's pixels; platform::windows::present_changes_only). Renderer::draw draws many rectangles that cover at least half their bounding box as that box, once (a Settings scroll frame was ~90 overlapping ones, each drawing every quad it met), and clears a whole pixel at a time; Engine::draw_quad fills a solid quad that reaches past its clip with no round corner inside it as just the shared rectangle (tiny-skia rasterized the whole path and masked each pixel after: a 4K window's background for a sidebar glide). raster::Pipeline::blit also scales an opaque image Nearest at any fraction of a pixel (raster::scaled), and engine::fill_rect blends a canvas's solid non-AA rectangle straight into the pixels; both split big areas between the cores (raster::rows): the zoom redraws the whole screen each frame (#89). Renderer::base (#89): where the first layer starts with an opaque picture drawn Nearest that covers the damage (the frozen screen), nothing is cleared under it, and a picture faded over one opaque solid rectangle (overlay::Zoomed's dim) is drawn over that colour in the same pass (raster::scaled); layer::same_image compares images by handle id (upstream compared a 4K frame's 33 MB of pixels on every frame), a canvas drawn anew the same is unchanged, and a primitive damages where it draws (a stroke's width included; a cached canvas only there, not its whole bounds). Timing: frame_times::settings_frame_times (by hand, release). Drop each once iced has it upstream; re-apply on an iced upgrade if not. |
vendor/iced_winit/ |
iced's window shell 0.14.1 with one OpenCircle patch ([patch.crates-io], marked OpenCircle patch in src/lib.rs): every visible window is drawn right after the update that changed it, and a window drawn for another reason draws the others changed meanwhile (Window::stale), from a local queue (redraws) before the next event. Upstream waited for each window's WM_PAINT, which Windows sends only while no input is queued and to the topmost window first: during a drag on one overlay window, another screen's window (a box across two screens) drew only after the drag. A redraw with nothing changed costs no raster (empty damage). Test: frame_times::other_windows_draw_with_the_one_that_draws (keeps the patch), the VM log's drag, screen at lines (each screen's frames during a press). Drop it once iced draws every window on time upstream. |
assets/lucide/ |
Icon font: a subset of Lucide (ISC, see its LICENSE) with only the glyphs we use. |
- Trigger: shortcut, tray or
opencircle capturesendsTrigger::CaptureorTrigger::Quickinto one channel. - Capture:
capture::mouse_first()(snip:every_monitor()) returns aFrame(RGBA, size, origin, scale). It runs on its own thread (a Wayland portal can wait minutes for the user's OK);Message::Capturedthen shows the pre-created window. - Overlay: the RGBA bytes become the
image::Handledrawn full-screen. The same bytes are later cropped by actions (shared, never copied whole). - Selection: the canvas reports press/move/release (screen px; the App maps them
to image px through
overlay::View); on releaseoverlay::settledecides: a zig-zag (3+ sharp corners) = a scribble (the box of its padded convex hull, which is also the clear area), a mostly straight drag = the rectangle it spans, anything else = the loop's bounding box, a tap = the word there (features/text_reading/app/word.rs). A new press starts over (redraw); a press on a corner handle resizes, on highlighted words a drag stretches them across lines (Shift+click too), elsewhere inside moves; Shift adds a selection (Ask AI / Text get every crop stacked in one image, the rest the box around all). The ask bar at the bottom opens Ask AI with its text (in "wait" mode, Enter with nothing typed = Search). Its buttons: Include screen, Copy, Save, Translate, Live, Music, Edit (no Search / Ask AI / Text buttons; their keys L / A / T stay). Text selection needs the screen's text. Who reads it isocr::route(App::system_text, decided per opening inApp::text_by): on Windows, Windows OCR (ocr::system) reads the whole screen from the capture on (App::open->read_more->read_bandof the whole screen, a below-normal thread), first as it is (selectable ~0.14 s after the first frame), then under 150 % doubled, which replaces it (system::passes); a failed read (no recognizer, an RTL language) falls back to the helper for that opening. The engine is freed after 60 s unused. Otherwise (Linux,pp_ocr, Arabic) the helper reads on demand, never at open (#123;word::Screen,App::read_more): nothing is read while the opening animation runs; after it the held helper starts (App::warm). A press, tap, Shift+click or Ctrl+A reads the full-width band under it first (at once,text_reading::read_screenwith only the band's new rows and the frame's rows around them); once text was used (off Windows: once the helper is warm,Message::Warmed, so the I-beam shows over text before any press), the rest follows band by band, nearest the pointer first, gently (the helper on at most two cores, below normal priority:features/text_reading/worker.rsGentle). One band at a time. A drag that began on text before its band arrived becomes a text selection then; one let go before it is held (with the keys after it, e.g. Ctrl+C) until it arrives (App::held). Without the OCR models a note over the bar (App::reader_note, stateReader) offers their download, one click. - Action: a bar button, Enter (the first action) or the action's key sends
Message::Run(&Action).App::runcrops the selection in physical pixels, then:Run::Finish(f)closes the overlay (so dialogs aren't under it) and callsf(crop)on a thread (App::confirm_after: encoding, clipboard, file; its pill comes back asMessage::Confirm). Clipboard writes and link launches never run on the UI thread;Run::AskAiopens the AI chat over the frozen frame (the bar hides, the selection stays). Slow work (PNG, browser launch, keyring, HTTP stream, model download, OCR) runs on a thread viabackground; results come back asMessage::AiChat(id, ai_chat::Msg)and stale ids are ignored. Dropping a panel aborts its task, which disconnects the thread (an AI stream then stops). - Close: Esc (any focus) or a finishing action:
close()takes the whole per-capture state (app/opening.rs: add new per-capture fields THERE, never toApp): the panel and the frame go; the window shrinks, then hides (Hiding).App::oisNonewhile closed (opening::Open);updatedrops every message that needs an opening then (update::works_closed: a new message that must work with no overlay open goes in that list). A press outside the panel starts a new selection and drops the panel.
Hide or show an unfinished feature (Labs): src/features/settings/labs.rs is the one place: a Feature, its [labs] switch
(Labs, parsed in shared/config/parse.rs, all off by default), and the data the rest reads: action_feature (which action id
belongs to it: shortcuts in hotkey::plan, opencircle run, actions::for_key), bar() (the bottom bar's buttons),
tray::entries, settings::pages::PAGES (lab) / slots. Never an if on a feature elsewhere: add it to that data. A hidden
feature keeps its settings in the file. A feature that ships leaves Labs (Snip, 0.1.3): its Feature goes, its [labs]
key stays in Labs, read and written unchanged (an older OpenCircle reads it) and used for nothing. Schema changes: bump config::VERSION; a step that changes a value goes in
Config::parse (it knows the file's version, e.g. schema 3 sets selection.after to "wait"),
and config::migrate copies the old file to config.toml.bak-v<old> and rewrites it.
Keep a new kind of record (a search index...): a file in src/shared/store/ with its functions
(blocking: call them on a thread), and ONE new entry at the END of store::MIGRATIONS (its tables; never
edit a shipped entry). Never put image bytes or secrets in it; tests point store::test_path at a temp file.
Add an action that finishes at once (like Copy):
- Create
src/features/circle/actions/<name>.rswithpub const ACTION: Action = Action { id, label, tip, key, icon, run: Run::Finish(run) }and itsfn run(crop: Crop) -> Result<(), String>(copycopy.rs; keep blocking work off the UI thread, seesave.rs). Keys: DESIGN.md "Shortcuts". - Add
mod <name>;and<name>::ACTIONtoACTIONSinfeatures/circle/actions/mod.rs, in action-bar order. The first entry is the Enter default. - Icon: the subset font has search, sparkles, type, languages, pencil, copy,
download, arrow-up, square, x (codes in
assets/lucide/subset.sh). For another glyph, add its code tosubset.sh, run it, commit the.ttf. cargo test: the registry tests check ids, labels, tips and keys are unique and that the icon is in the font.
Add a quick action (its own shortcut, not a selection action): a QuickId variant (its name is the file's), its Labs feature in labs::action_feature, its Settings name and hint (settings::state::action_name / quick_hint), and its unbound entry in Config::add_new_quick_actions (the default file stays byte for byte; Settings shows the row, the file gets it at the next save; opencircle run <id> needs no entry).
Add an action that stays on screen (a card like the AI chat):
- As above, with its own
Run::<Kind>variant (likeRun::AskAi). The action file holds the work (blocking functions, pure logic + its tests). - In
features/ask_ai/screens/ai_chat/(or a screen of its own): aStatevariant, its start inAiChat::open(slow work viabackground, keep the abort handle inworkif it should stop with the panel), itsMsgs inAiChat::update, its body inview.rs(kit parts only). Messages the App must act on (close, open another panel) are matched first inApp::on_ai_chat.
Add a shared widget: screens never set a style themselves; they take
their controls from the kit (shared/kit/: one file per
control, styled only from kit::tokens / kit::themes, no config or clock, motion as an
f32 progress). A new kit
control lands with its first user and gets a gallery sheet in kit/testing/gallery.rs
(states as rows, Latin + Arabic, Sapphire + Daylight; tests/fixtures/kit/,
arch_tests::every_kit_component_has_a_gallery_sheet).
arch_tests::screens_never_style fails on any screen that styles in place.
A control a press reaches is a keyboard focus stop: build its button with
focus::press(button, radius, on_press) (or focus::stop(..).steps(..) for a
value the arrows step); a press that is mouse-only by nature (a drag, a resize
edge, a caption button) carries // mouse only: <why>
(arch_tests::every_kit_press_is_a_focus_stop). A window gets Tab / Shift+Tab by
putting its view in focus::scope (Settings does); a question's Cancel is
button::cancel / setting_row::cancel and the screen focuses focus::CANCEL
when the question opens.
Add a Settings page: one Page entry in features/settings/pages/mod.rs PAGES
(its Section, title, optional note / sidebar badge / Labs feature) and one view file
beside it that composes kit parts (setting_row, segmented, card, …); a golden in
the_ported_pages_match_their_golden_images (Sapphire + Daylight).
Goldens render with the bundled fonts only (kit::text::load, test builds off Windows): the test font system
drops every system face, so a golden never depends on the machine (CI's image and a dev PC have different fonts). A
character the bundled faces (Inter, Noto Sans Arabic, JetBrains Mono subsets) don't cover (Cyrillic, Greek, Hebrew,
CJK, Hindi, Thai, Latin Extended-A) is the same missing-glyph box everywhere, by design; text meant to show must use
a kit font (kit::text::*, never a bare iced::widget::text without .font). Windows keeps its own fonts and does
not compare goldens (golden::enabled). the_language_names_the_pickers_show_are_covered_or_listed lists the
languages whose names the bundled fonts don't cover.
Add a feature preview (the hero at the top of a feature's Settings page, only for a
feature that ships; owner 2026-10-27/28): one Hero entry in
features/settings/previews/mod.rs HEROES (its page, hidden_previews key, title, line,
optional Labs feature, shortcut, clip names), the still at
assets/previews/stills/<clip>.webp (bundled by build.rs; none = no preview) and the
clip's pin in previews/online.rs CLIPS (1080p AV1 IVF on the models repo's
previews-1 release; spec: docs/previews.md). Nothing is downloaded before "Play preview"
(Message::Fetch -> Outcome::Fetch, models::ensure). previews::player runs one thread
per preview (still, then the page's clips in turn in a loop, decoded by rav1d in
previews::av1 at the stage's px width, kit::hero 16:9 Media); dropping it (page left,
Settings closed) ends it. Tests play tests/fixtures/previews/tiny-{a,b}.ivf
(State::play_clip).
Animate a widget: keep its motion in ui::kit::motion terms: a Shown (open/close by
WIDGET or TOAST_PACE) or the time it began plus a token (OPEN, CLOSE, MORPH,
GLIDE, DOCK, TOAST) and a Curve, set on the first Message::Frame that sees it;
never another duration (reduced motion is handled there). Add it to App::animating
so the frame clock (motion::frames) ticks while it runs. A whole window (popup,
overlay) fades with windows::appear / windows::close / windows::fade (its
opacity, on Windows); inside the overlay a widget only moves or scales (no alpha
for a group of widgets on the CPU renderer). Over the frozen frame only the moving
widget may redraw: keep the overlay canvas's inputs (overlay::Shown) unchanged,
and check with frame_times::frames (its damage) and animation_frame_times.
Change who reads the screen's text (main mode): ocr::route is the one decision
(setting selection.text_reader, Windows OCR's language from ocr::system::known), with
its table test main_mode_text_is_routed_to_the_right_reader. An engine returns
Vec<ocr::TextBlock> (lines, frame px) and features/text_reading/app/word.rs (lines, measure) makes them
selectable, whoever read them; Windows' words become lines in ocr::system::blocks.
Selections and one-shot translate call PP-OCR directly (recognize_in_child); live mode follows
ocr::route too when Windows OCR reads its source language (features/live_translate/screens/live_layer.rs Reader, #56).
Settings > Look & behaviour > Text reader (Windows only) sets the setting; its note about a missing
Windows recognizer comes from ocr::system::missing (installed list x display language + translate
source) and its button opens ms-settings:regionlanguage (nothing is installed by us).
Add a string (any word a screen shows): one entry in src/shared/app_language/strings.rs, key: "English" | "Arabic";
(the key names the screen and the thing: g_lang_desc), then t!(key) (or tr(S::key)) where it is shown; a value
in a sentence is {} and goes through app_language::fmt(S::key, &[&value]) (in Arabic a Latin value is isolated,
U+2068/U+2069), a count through app_language::count(n, [one, two, few, many]) (Arabic's plural forms). Never a
literal: app_language::tests fails on a key without both languages, a key no code uses, and any word left in a
Settings or onboarding file (NOT_UI lists the literals that are not words: key names, ids, the CLI). The kit takes
its few words as parameters (hero::Words, shortcut_field's "Not set"): it never reads the table.
Add a language: a Lang variant (+ code, rtl, its lang_<code> name key for endonym), a column in the
table's macro ([en, ar, …]) and its text in every entry, a Choice in CHOICES (Settings' App language list). The
language resolves from general.app_language (Settings; "" = follow), else general.language (onboarding's pick), else
the OS's (app_language::of_config); apply sets it on the UI thread (Settings' state at open and on a pick,
onboarding's language step): the next redraw of every window speaks it, no restart.
Make a screen direction-aware: its view starts with let _dir = kit::dir::scope(app_language::rtl()); (the kit
reads the direction while the view builds; views that don't set it stay left to right), writes its side-by-side
children in reading order with dir_row![a, b] / kit::dir::row(vec) (never row! with a .push after it: the push
lands at the wrong end in Arabic), aligns text columns with .align_x(kit::dir::start()), pads one side with
kit::dir::pad, and uses Icon::directed() for arrows. The kit parts do the rest (setting rows, sidebar, header with
the caption buttons top left, segmented/Off-On order, slider and progress from the right, dropdowns, cards, hero).
Never mirrored: key caps, numbers, paths, URLs, the logo, colour strips, preview stages. A wrapped right-to-left
paragraph goes in a column (a sub straight in a container was laid out past its edge). Older screens with their own
rtl: bool (Snip toolbar, Steps strip, ruler, long-capture hint, option_list::foot / ActionRow) take
kit::dir::rtl() when they move onto the table (part 2b); the language picker, option_list::{opener, choice, group}
and field::search already do. A floating window (toast, update pill / card, tray menu: ui::windows) is built and
its size measured inside windows::spoken(..); the translate session's view sets the direction itself. Backend code
never writes a sentence the user reads: it returns a typed value (update::Answer, hotkey::Reserved,
config::ShortcutFault, ai::models::Tag, the settings Why, ocr::OcrError) whose Display stays English for logs
and tests, and the UI maps it to table keys (general::answer_words, model_download::why, model_list::ai_words).
A pill text a backend names is Said(S::key) (actions::copy::COPIED_PILL). The release notes are the release's own
English text: the What's new card keeps them as one left-to-right block (update_card::quoted).
Change the per-game glossary (0.2.0): the data and the rules live in features/translate/glossary/ (mod.rs: matching,
apply / restore / Applied::fix number placeholders, whole, stamp, ai_terms; store.rs: one TOML per game in
<data>/glossaries/, validated import, current() = the glossary in use, picked by translate.glossary or, where the OS gives
a title, by the glossary's windows list). The pipeline calls it in ONE way each: pipeline::through_with (terms as numbers
through the models, a lost number = that line again plain), on_device_with (a line that is a term, before the menu table),
translate_blocks (the cache key carries stamp), Real::lines (AI terms, soft). Screens: Settings row + editor
settings/pages/glossaries.rs (a sub-page of Translate; Message::GlossaryEditor opens it), the pill's button and list and the
word card's form translate/screens/pill/glossary.rs. The focused window's title is window_rect::focused_title() (Windows,
X11; Wayland none), remembered at capture start. Other features reach it only through translate::{Glossary, Term, glossary_store}. New file field = an optional key in store::File / Entry, never a breaking one (files are shared).
Name suggestions (0.2.0, #180): glossary/suggest.rs counts capitalised names per game on translated game screens
(pipeline calls suggest::observe once, off-thread; counts in <slug>.names.json, rejections in the glossary file's
rejected); the pill's dot and list read suggest::pending. A name shows on >= NEEDED different screens.
Add a colour: a theme colour goes in every theme of kit/themes.rs; one
that is the same in every theme in kit::tokens::fixed. Nowhere else.
Add an active look (a preset): a LookTheme variant and its row in
config::PRESETS (a new colour set: a ColourSet variant and its colours in
theme::colours), then its tile in features/settings/state.rs LOOKS. The tests check
every preset round-trips and draws no key colour on the live layer.
Read them through sys::test_hook: a release build (what the VM builds and users run) reads a hook only
with OPENCIRCLE_TEST_HOOKS=1 set too; debug and test builds always do. OPENCIRCLE_TEST_UPDATE_URL stays
outside it (the update gate runs published builds).
OPENCIRCLE_TEST_FRAME=<8-bit RGBA PNG>: capture returns this image instead of the screen.OPENCIRCLE_TEST_LANGUAGE=<tag>(e.g.ar): the OS's language assys::locale::languagereports it: the setup window and a fresh onboarding speak it (VM runs in Arabic without changing Windows' display language).- With the editor open, its Esc (Back) takes the test shot (
OPENCIRCLE_TEST_SHOT). OPENCIRCLE_TEST_LIVE_SHOT=<out.png>: live translate saves its layer once the first patches (or the first error) are drawn.OPENCIRCLE_LIVE_LOG=1: Live's log lines per stage (detect / read / translate / draw / hide, with times).OPENCIRCLE_LIVE_BOX=1|0andOPENCIRCLE_LIVE_TYPED=1|0: box memory and the whole-sentence typed-out path on or off, for A/B runs (the app runs both off in 0.3.0; the core's own default has typed-out on).- Live replay (ignored tests in
live_translate/live.rsandlive_core/tests.rs, run byscripts/live-replay-check.sh):OC_CLIP=<dir>/<clip>(a harness clip + its truth),OC_FIXTURE=<dir>/<name>(a recorded fixture),OC_TYPED=1|0(typed-out on / off),OC_FPS(frame rate),OC_LAT(engine latency),OC_BOXPAD,OC_TRACE,OC_PAD/OC_SLOW(the Ubuntu VM's window and slower jobs),OC_DBG(list missed / redrawn texts). OPENCIRCLE_TEST_UPDATE_URL=<release JSON URL>: the update check asks this URL (http allowed: a local fake release server) 3 s after start, also from a 0.0.0 build. Downloads still need a signature byRELEASE_PUBLIC_KEY, or, only with this hook, by a throwaway key baked in at BUILD time (OPENCIRCLE_TEST_RELEASE_KEY; release.yml never sets it).scripts/update-gate.ps1drives it as the release gate (docs/RELEASING.md step 9).OPENCIRCLE_TEST_CAPTURABLE=1: our floating windows (Steps strip, pins, pills, the pinned chat's, tray menu; the update's pills and card always show) are not excluded from screen capture on Windows (VM screenshots of them over the desktop; they then also show in the next capture's frozen frame). Linux takes them out of each grab but Snip's (Windows::leave_frame) whatever this says. Snip's grab always has them in, as targets (window_rect::widgets_in_grab; owner, 2026-11-10).OPENCIRCLE_TEST_SHOT=<out.png>: Esc saves what the overlay shows before closing (shot ~150 ms after Esc, with no message in between: a relayout would drop the text editor's drawn text from the shot).