craft-theme-store
The Craft suite's theme files, the machine-local theme library and the shared suite selection,
outside rendering. Several apps can change the selection and the library at the same time
without losing a change: every write takes a lock, re-reads the file, merges and bumps a
revision. No egui; the theme contract (ids, the theme model and file format, built-ins, the
selection and its resolution) is
craft-theme. docs/suite-themes.md
describes the file format, the folder and the protocol.
use craft_theme_store::{SelectionChange, Store, StoreError, StoreOptions, SuiteDir};
// Desktop shells only; app constructors, tests and web builds use SuiteDir::memory().
let mut store = Store::open(&SuiteDir::resolve(false), StoreOptions::new("pdfcraft 0.15.0"));
let _ = store.load_selection(); // a problem keeps the last accepted state
// What the app shows while following the suite: chosen fields, its own defaults for the rest.
let shown = store.accepted().suite.with_defaults(&app_defaults);
// The user picks a theme: only its slots are written (both for a two-variant theme, else its own
// mode's). base is the accepted state the UI showed.
let base = store.accepted().clone();
match store.update(&base, SelectionChange::pick_theme(&picked)) {
Ok(accepted) => { /* show accepted.suite.with_defaults(&app_defaults) */ }
Err(StoreError::Conflict { disk, mine }) => { /* "Changed in another Craft app"; "Apply mine" sends `mine` with `disk` as base */ }
Err(e) => { /* back to store.accepted(), show e with Retry */ }
}
| Item | What it is |
|---|---|
SuiteDir |
CRAFT_SUITE_DIR (empty: in memory), in memory for isolated apps, else ArtCraft/themes in the local config folder |
Store |
load_selection, update, import, delete, export, library, load_theme, theme (a resolve lookup) |
SelectionChange |
the fields the user changed (theme_light, theme_dark, mode, contrast, size, text_size); only these are written, each merged on its own |
Accepted |
suite (craft-theme's SuiteChoice: each field None until a user chooses it), revision, library_revision; serde, for the copy apps keep in their preferences |
StoreError |
Busy, Conflict { disk }, IdExists, InUse, … ; nothing on disk changed |
Problem |
damaged, too new or unreadable files; the store keeps its last accepted state |
ThemeRecord, ThemeEntry, format |
a parsed user theme file (craft-design-theme v1, craft-theme's format) with its stored bytes, unknown keys included; the library skips files in another format, such as the pilot's craft-theme |
SuiteClient |
what an app calls: per-frame sync, the optimistic shown choice, change, conflict and failure notices with apply_mine and retry, the theme lookup, preview for any theme's picker card |
SuiteWatch, Snapshot, Op, OpOutput |
the store on a worker thread: snapshots by generation, queued operations with results |
ui (feature ui) |
the Preferences appearance page AppearancePage (modes, light and dark theme rows of ThemeChips with favorites, Size and UI Font Size; tokens theme_chip.*); feature screen-testing adds egui_kittest input tests of the page |
FileStamp, library_files, selection_stamp, theme_stamp, parse_counts |
cheap change checks for a watcher |
Store methods block on file I/O and on the lock (up to 2 s). Apps use SuiteClient over a
SuiteWatch, which owns the store on a worker thread, instead of calling them on the UI thread:
use craft_theme_store::{SelectionChange, StoreOptions, SuiteClient, SuiteDir, SuiteWatch};
let options = StoreOptions::new("pdfcraft 0.15.0").last_accepted(prefs.last_suite.clone());
let watch = SuiteWatch::open(&SuiteDir::resolve(false), options, move || ctx.request_repaint());
let mut client = SuiteClient::new(watch); // SuiteClient::memory() in constructors, tests, web
// Each frame: one atomic load unless something changed.
if client.sync() || choice_changed {
let selection = app_choice.apply(&client.shown().with_defaults(&defaults));
let shown = resolve_selection(&selection, system, fallback, &defaults, Some(&app), &|id| client.theme(id));
// tokens from `shown.resolved`; save client.accepted() as prefs.last_suite
}
// The user picks a theme, mode, contrast, size or text size; shown() reflects it at once.
client.change(SelectionChange::pick_theme(&theme));
// Notices: client.conflict() with client.apply_mine(), client.failure() with client.retry()
// (StoreError::Lost when more than 16 other results pushed the answer out between two syncs),
// client.problems() for files the suite can't use.
// Picker cards: client.preview(id) for built-ins and every library theme, no export needed.
The worker stats selection.json every 500 ms and compares its bytes every 10 s, parses only
what changed, re-lists the library only when its revision changes or on Op::Rescan, and calls
wake only when the snapshot changes. SuiteWatch::memory() runs without a thread and without
wake calls (the caller is in its frame already); on wasm32 that is the only form. docs/suite-themes.md
has the details.
In memory, each Store has its own state: open one per process and share it.
The testing module has SAMPLE_THEME_JSON with its pinned colours (sample_colors), for each
app's adapter test, and FailingFs, a file system that fails one step of a write.
The lock file and revision protocol, the re-check before the rename, the failure handling and the stamp-plus-bytes change detection follow the theme store in pdfcraft#1090 by mjshfrvstj-sys.