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

98 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Canvas Pilot theme packs, version 1
Implementation: `crates/canvas-pilot/src/theme_packs.rs`. User instructions and
editable examples: [Add a theme pack](../canvas-pilot/guide/theme-packs.md).
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](canvas-pilot-settings.md) 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](canvas-pilot-settings-v15.example.json) 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.