mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 21:52:32 +00:00
105 lines
12 KiB
Markdown
105 lines
12 KiB
Markdown
# craft-platform
|
||
|
||
Small platform lifecycle services for Craft applications. Application state, settings, palettes,
|
||
document policy and native command routing remain in their current owners. Only the services a host enables
|
||
pull in heavier dependencies.
|
||
|
||
| Feature | Shared responsibility |
|
||
| --- | --- |
|
||
| default | Typed dialog outcomes; `PlatformText`; `open` (see below); no backend or toolkit. |
|
||
| always (not wasm) | `dialogs`: reserve waiting workers before eager UI-thread native picker creation; serial requests, failure delivery and completion wakeups. The backend factory belongs to the app. |
|
||
| always | `From<appearance::Reading> for craft_theme::SystemAppearance`, so a host hands the OS answer to `Base::resolve`. |
|
||
| `pointer` | Move the system pointer (`pointer::warp`), installed by the app as craft-ui's `Scrub::install_warp` service for a scrub's screen-edge wrap; macOS only, `false` elsewhere. |
|
||
| `appearance` | Linux/BSD XDG desktop preference observation (colour scheme, contrast, reduced motion, button layout); browser contrast and motion media queries; owned cancellable subscriptions, bounded reads/helper capture, legacy compatibility and reconnect. |
|
||
| `browser` | Wasm download link/object URL ownership, cleanup on setup failure or abandonment, and cleanup timer registration before clicking. |
|
||
| always | `clock::Clock`: monotonic seconds (`web-time`, so also in the browser) for animation, autosave and deadlines, with a manual mode tests set and advance; `monotonic_ms`, `unix_ms`. |
|
||
| always | `pacing`: `FrameCap` (desktop frame-rate cap without vsync), `WindowVisibility` (shown or hidden), `WorkBudget`/`WorkSlice` (background work per call, paused or sliced while hidden). No egui. |
|
||
| always | The app log: `log` records to standard error and `<dir>/<app>.log` with `RUST_LOG`-style filters, rotation to `.1`/`.2`, per-instance logs while another instance runs, a size cap; `logs::crash`: the panic hook, crash log, last panic for the error window, and `catch`. |
|
||
| always | `session::Session` and `SessionKeeper`: the documents open at the last quit and where the user was in each, stored in the app's settings (serde) for a "Reopen Last Session" preference; `to_reopen` skips what is already open; a stored list longer than 64 documents is cut. No egui. |
|
||
| `usage` | `usage::sample`: the process's resident memory and the memory it may still use (`MemorySample`, `None` when unknown), for the status readout's Scratch and Efficiency items. Linux reads `/proc`; other platforms return `None`. |
|
||
| always | `open::FileIntake` with `IntakeSender` (the app's Apple Events and second-instance hand-over feed it): one queue for files the OS asks the app to open and files dropped on the window (`DroppedFile`, `DropTarget`: canvas, tab strip or window); `natural_cmp` and `same_file` for opening order and duplicates; `reveal` and `open_external`; the shared open-error texts. No egui. |
|
||
| always | `autosave::Autosave` (the timer: which documents are due, results by revision), `recovery_dir`, `adopt_legacy_recovery` and `RecoveryStore`: the recovery folder of copies with a JSON sidecar each (`RecoveryEntry`, the fields craft-ui's `RecoveryDialog` lists), `AUTOSAVE_FAILED`. The app serializes its documents. |
|
||
| `clipboard` | `clipboard::Clipboard` over a `ClipboardBackend`: every copy and paste goes through it, with size limits (`ClipboardLimits`, `TooLarge`), a fence that keeps synthetic (automation) input from replacing what the user copied, and `holds_ours` to tell the app's own copy from another app's. `SystemClipboard` (arboard) reads and writes text, HTML, one bitmap and copied files; `EventClipboard` is the browser's, fed from paste events (`flavors_from_event`, `copy_through_egui` with `ui`). `EventClipboard` keeps an offered paste for the pass it was offered in and counts passes itself (`EventClipboard::for_egui` uses egui's pass number), so a menu Paste in a later pass finds nothing and the app has nothing to call at the end of a pass. A write reports which flavor the backend wrote, and `holds_ours` compares that one. The web writes only the best flavor (eframe makes each copy command its own `navigator.clipboard` write, so a second replaces the first). `has` never reads or decodes: it asks Windows and macOS for the formats on offer, Wayland for the offer's MIME types (`wl-clipboard-rs`) and X11 for the `TARGETS` list (`x11rb`); a bitmap counts only as `image/png`, the one arboard reads on Linux. `ClipboardProbe` asks a second handle on a worker thread whether Paste has anything, so a slow owner never stalls a frame. Bitmaps are read as straight RGBA8, not PNG: the `BITMAP` and `RGBA8` reads return an `image/x-rgba8` flavor (width and height as little-endian `u32`s, then the pixels) and `read_image` returns `ClipboardImage`; the crate has no PNG encoder, and `SystemClipboard::decoder` takes the app's PNG decoder for writes. SVG, PDF and RTF flavors are neither written nor read by `SystemClipboard` (a write of only those fails with `Other`); a bitmap offered only as `image/jpeg` or `image/bmp` on Wayland reads as `None`. |
|
||
| always | `watch::FileWatch` and `Changed`: open files that changed on disk. One worker thread (`craft-file-watch`) compares each file's metadata (`FileStamp`) every 250 ms and sleeps while nothing is watched; a changed file is reported once it has settled and, with `ReadPolicy::Whole`, looks complete. The app's own saves are recognised by `known_now`; `disk_differs` answers at Save time; `take_changes` runs on the frame the worker's `Wake` asks for. |
|
||
| always (native) | `default_app::make_default`: the Preferences button that makes the app the system default for its file types. Windows opens Settings › Default apps (`SettingsOpened`), Linux and BSD run `xdg-mime default` (`MadeDefault`, refused inside Flatpak or without an installed desktop entry), macOS answers `Unsupported`. `path_from_arg` and `rejoin_split_paths` read the paths a launcher hands the app. Only a button may call it. |
|
||
| always (native) | `temp::TempDir` and `TempFiles`: private temporary folders created exclusively with owner-only permissions (`0700`, files `0600`, `create_new`), named with the process id and a counter, removed on drop. |
|
||
| always | `PlatformText`: a user-visible message of a platform service (id, English text with `{name}` placeholders) that the app looks up in its own catalog. The open, clipboard, watch, default-app and temp services and craft-dialogs' save flow use it. No words table lists them yet, so the missing-translation list does not show them. |
|
||
| `screen` | Screen capture for the screen colour picker (`craft_platform::screen`). |
|
||
|
||
|
||
## Native dialogs
|
||
|
||
`dialogs::wait_prepared(create, deliver)` reserves the worker first. Call it on the native UI thread.
|
||
`create` must call `pick_file`, `save_file`, or the equivalent backend method **before returning its
|
||
future**. Putting that call inside an async block delays native sheet creation until the worker
|
||
polls it. Worker reservation failure never opens the sheet. No live picker has a timeout.
|
||
|
||
`NativeDialogs<Request, Answer>` provides an optional serial queue. Pump it on the event-loop
|
||
thread before consuming answers and after code that can request a picker. Replies become visible
|
||
only after the pump releases transport ownership, so a continuation can enqueue the next picker.
|
||
Dropping a stale reply does not release the actual picker. A host-specific preflight is optional;
|
||
it runs off-thread and must be bounded. Unknown capability permits a picker. Proven absence may
|
||
request an application-owned fallback. Custom save-format sheets and portal choices remain intact.
|
||
|
||
`Outcome::Selected`, explicit `Cancelled`, `Failed` and `Indeterminate` have different evidence.
|
||
An rfd `None` is `Indeterminate`; it cannot prove user cancellation rather than backend failure.
|
||
Disconnected workers are failures. Apps own localization, document identity/revision checks, filters,
|
||
actual save receipts, chained continuations and the decision to close.
|
||
|
||
Retain the actual parent window through queued requests, preflight, the native picker AND any
|
||
unconsumed application continuation. A close request that arrives meanwhile never grants permission to
|
||
discard work: the app runs its normal close policy again afterward.
|
||
`appearance::Watcher` caches the desktop preference and wakes only on changes. Subscription precedes
|
||
the first read. ReadOne/legacy Read, the standard namespace and GNOME fallback are handled together;
|
||
on GNOME the "default" (Light) setting and portal value 0 read as light; elsewhere 0 is no preference.
|
||
Malformed values retain the last valid answer, and explicit no-preference clears it.
|
||
`SystemReader::read()` gives colour scheme, contrast and reduced motion in one call on every target: the watcher on Linux/BSD, the browser media queries on the web, no answers elsewhere.
|
||
|
||
`Watcher::wait_first(timeout)` blocks until the first answer, a known absence, or the timeout (about 250 ms in an eframe creator), so the first frame uses the desktop theme. Disconnection
|
||
retains the last valid value until a fresh answer. A later service owner triggers a reread; session
|
||
reconnection has bounded backoff. Dropping cancels asynchronous work and waits at most 100 ms
|
||
for acknowledgement, joining only an already-finished worker. A synchronously blocked OS call or caller wake callback can outlive
|
||
the watcher: that exceptional worker is detached and retains its resources until it returns,
|
||
possibly until process exit. Wake callbacks must be nonblocking. No per-helper reader threads
|
||
are created.
|
||
|
||
App-selected Light/Dark/System, custom palettes, window decorations and unknown-theme fallback remain
|
||
application policy. `set_active(false)` suppresses wake notifications while continuing to cache.
|
||
Four existing custom-palette service hooks retain their current signatures and receive change-only
|
||
notifications even in manual mode; they do not change the chosen palette.
|
||
|
||
`Watcher::button_layout()` is GNOME's `org.gnome.desktop.wm.preferences` `button-layout`, read and
|
||
followed on the same portal connection (ReadOne, then legacy Read; `gsettings` once when the portal
|
||
has no answer). It is the string as the desktop reports it, `None` until one arrives, and a change
|
||
runs the same wake callback. Malformed values keep the last one. `wait_first` does not wait for it.
|
||
`craft_window::policy::LayoutWatch` turns it into the caption layout; craft-window takes the string,
|
||
so it needs no D-Bus dependency.
|
||
|
||
### Contrast and reduced motion
|
||
|
||
`Watcher::contrast()` (`Contrast::Standard` or `High`) and `Watcher::reduced_motion()` follow the
|
||
portal's `org.freedesktop.appearance` `contrast` and `reduced-motion` keys. Without a
|
||
`reduced-motion` key, GNOME's `org.gnome.desktop.interface` `enable-animations` stands in. Both
|
||
are read beside the theme, so `wait_first` returns with them, and a change runs the same wake
|
||
callback. `None` means no answer yet or no such key; the `gsettings` fallback doesn't read them.
|
||
macOS and Windows have no watcher (their settings need platform bindings, and the crate forbids
|
||
`unsafe`). On the web, `browser_contrast()` and `browser_reduced_motion()` evaluate the
|
||
`prefers-contrast: more` and `prefers-reduced-motion: reduce` media queries on each call, with
|
||
no change notification.
|
||
|
||
## Browser downloads
|
||
|
||
`PreparedDownload::{bytes,blob}` owns a detached anchor and URL until click or drop. Call `click`
|
||
with the application's positive URL lifetime; setup/attachment/timer failure releases resources
|
||
without clicking. A successful return means a click was issued, not that the browser saved a file.
|
||
Applications own names, MIME types, pacing, capture hooks and user activation. File System Access
|
||
and print iframe lifetimes remain separate. This service has no native filesystem semantics.
|
||
|
||
## Integration
|
||
|
||
Enable only the services a host uses. Applications retain palettes, settings, document identity,
|
||
close policy, filters, names, MIME types and native command routing. Existing craft-settings,
|
||
craft-atomic, craft-print, craft-docpath and craft-quit remain canonical. `craft-window` owns
|
||
decoration selection and window-button layout; appearance observation here
|
||
do not choose a frame or draw an application header.
|