canvas-pilot/docs/interfaces/theme-packs.md

5.9 KiB
Raw Blame History

Canvas Pilot theme packs, version 1

Implementation: crates/canvas-pilot/src/theme_packs.rs. User instructions and editable examples: Add a theme pack. Supported from Canvas Pilot v0.9.26.

Archive and palette representation

A ZIP contains exactly one regular root file named manifest.json. Directories, symlinks, other paths, extra entries and unsupported ZIP compression/encryption are rejected. Nothing is extracted. Maximum archive size is 2 MiB; the manifest has a 4 MiB expanded limit enforced while reading. CRC/decompression failures reject the pack. JSON is UTF-8; unknown fields and unsupported versions fail. Repeated JSON object keys have serde's last-value behavior; authors must use unique keys. Array order determines theme order within the pack.

Field Representation and validation
version Required integer 1
id Required pack ID: 1–63 lowercase ASCII letters, digits or hyphens, no leading/trailing hyphen
revision Required positive u64, 1–18446744073709551615; revision comparison is numeric
themes Required array of 1–16 themes
themes[].id Same identifier syntax, unique within this pack
themes[].name Nonblank display name, 1–160 UTF-8 bytes, no control characters
themes[].light Required boolean selecting egui light/dark base visuals
themes[].colors Required complete palette object, fields below
notices Optional attribution/license text, default empty; at most 65,536 UTF-8 bytes; controls forbidden except newline, tab and carriage return

Every color is an opaque sRGB string #RRGGBB, exactly six hexadecimal digits (case-insensitive). Channels have 8-bit precision; no alpha, gradients, numeric units or geometry are represented. The original ZIP bytes are preserved.

Palette field Use
bg, panel, field App background, panels/windows, input fields
line, text, muted Borders, primary text, secondary text
cyan, amber, purple Accent/handles, selected-layer/warning accent, selection/button fill
canvas, banner, grid, layer Viewport background, example banner, grid, layer fill
pattern Exactly two color strings for alternating source-helper tiles

The theme system derives hover colors from these roles and uses its existing light/dark error colors. Font families, text sizes, interface scale, geometry, layout metrics, source images and device behavior are not supplied by packs. There is no executable content or network loading. Authors are responsible for contrast; the examples test at least 4.5:1 for primary text on panel, field, selection and both source-helper tiles. Theme packs cannot override built-ins.

Installation, updates and removal

Packs live in <settings-parent>/theme-packs/<id>.zip. The logical choice is <pack-id>/<theme-id>, so separate packs can reuse a local theme ID. Installation validates the entire archive before writing; an update replaces the previously loaded path for that ID, even if its ZIP was manually renamed. A valid destination owned by another pack ID cannot be overwritten.

A new pack or higher revision installs immediately. Equal/lower revisions and an unreadable existing destination require overwrite confirmation. The reviewed source bytes are retained in memory; cancellation changes neither disk nor the loaded palettes. Before commit, destination bytes must still match those reviewed. Writes use a flushed temporary file in the destination directory, atomically persisted with no-clobber behavior for a new pack. Runtime registration changes only after persistence succeeds. Existing destinations over 2 MiB are not replaced.

Updates replace the entire theme list. The active palette refreshes immediately; if an update removes the active theme, Midra Dark is selected and saved. Removing a pack confirms its ID and included names, requires exact equality with its loaded ZIP bytes, then deletes only the installed copy. A changed/unreadable file leaves runtime state intact. Removing an active theme also selects and saves Midra Dark; other themes keep their selection. Unavailable recent entries are pruned during management, retaining a currently selected missing preference if unrelated to the operation. Source downloads are untouched.

Startup is offline, scans at most 33 ZIP paths to detect the 32-pack limit, sorts them and considers at most 32. Too many packs, invalid files and duplicate IDs produce errors without stopping startup; the first valid sorted file for an ID wins. Installing a 33rd ZIP is refused; updates at the limit are allowed. Manual changes to installed files take effect after restart.

Settings, missing packs and round trips

Settings version 15 stores a packed theme as {"pack":"tokyo-night/night"} in theme and recent_themes; built-in string IDs are unchanged. Versions 1–14 migrate preserving preferences and history, but pack choices under a legacy version are rejected. Older applications reject version 15. The default fixture is the migration target.

Missing/invalid packs preserve the saved theme choice and show an unavailable label, rendering with Midra Dark until the pack is installed again or the user selects another theme. Installation alone does not select an unrelated theme. Loaded palettes and selection are scoped to an egui context. High Contrast can return to a packed previous theme. Project, recovery and exchange files contain no pack palettes or theme preferences; their representations remain unchanged.

The editable manifests and ZIPs contain identical bytes, checked by Rust tests and python3 scripts/build-theme-packs.py --check. Lifecycle tests cover startup, selection persistence, live updates, overwrite review/cancellation, changed-file protection, removal, limits, malformed colors/archives and context isolation.