ltk/CHANGELOG.md

Changelog

All notable changes to ltk are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• The user's files, alike natively and in a browser: ltk::files — asynchronous operations on the user's files whose results reach the app as messages through its ChannelSender: list, stat, read, read_range, write, open_write, create_dir, rename, remove, remove_all, copy, copy_all, mount and unmount, each taking the sender and a done that turns the io::Result into a message. Natively they run std::fs on a worker thread of ltk's, and each copy on a thread of its own; in a browser they are forge/web's fs_* requests over the app's connection, contents travelling as a Uint8Array beside the JSON as the second argument of the connection's request and of the client's event handler, and what is asked before the app connects is sent once it has, or fails with Unsupported on a page without a desktop. Contents travel in chunks: a large file is read with read_range and written through a Writer, chunk by chunk, files::CHUNK (1 MiB) at a time, and its contents appear only once the writer is closed, a new file showing empty until then in a browser; natively it is written beside the file and renamed over it, and a writer dropped unclosed leaves the file as it was. A copy runs where the files are, reports its progress every 100 ms, never replaces an existing file, and, cancelled through its Operation or failed, leaves nothing behind. Errors are the same io::ErrorKinds on every platform. Entry and Metadata give a file's kind, size and times, the access time natively only. mount asks the browser for a folder of the user's computer, from the user's press, and fails with Unsupported natively. App::on_files_changed, App::on_mounts_changed and App::on_open_files hear of forge/web's fs_changed, fs_mounts and open_files. files::mime_type( name ) gives a file's type by shared-mime-info's globs2, the resource directory's mime/globs2 first, which scripts/android-assets.sh, and so web-assets.sh, now copies into the tree with shared-mime-info's subclasses (MIME_DIR overrides where from), then the system's. rename never replaces what is at to, natively as in a browser. Tests cover writing, aborting, listing, ranges, removing, copying a tree with its progress, a cancelled copy, a copy that would replace, and the globs.

• ltk::web::shell_request( json ) — a shell message that waits for forge/web's reply, such as get_window_thumbnail: sent as shell_send sends one and answered at once with forge/web's reply as JSON, or None before the app has connected, since a request is not kept for later, and when forge/web replies nothing. A shell's requests that wait for an answer natively got none in a browser.

• Canvas::draw_image_keyed( key, rgba, w, h, dest, opacity ) — draw_image_data with key naming the pixels in place of a fingerprint of them, so a caller that draws the same images on every frame, such as a terminal's glyphs, does not hash every one of them each time. Every draw with the same key must pass the same pixels, which are read only when the image is not cached; a key never names an image drawn by content.

• Fullscreen in a browser's desktop — on a page with forge/web, App::fullscreen and App::start_fullscreen ask forge/web for the main window to fill the desktop with a set_fullscreen request, as Wayland's xdg_toplevel.set_fullscreen, where they did nothing; alone on a page the app's canvas still takes the browser's fullscreen.

• A browser app hears of the desktop's windows — on a page with forge/web, the web backend asks for the list of toplevels when it connects and turns its toplevel_opened and toplevel_closed events into App::on_toplevel_event, as the Wayland backend does with ext-foreign-toplevel-list-v1, so a shell's dock knows which applications have windows open and names each by its identifier.

• A browser app tells the desktop it is shown — on a page with forge/web, each surface's first presented frame is reported with a presented request, as a Wayland client's first commit follows xdg_activation_v1.activate, so forge/web knows when a window it launched has shown and reports app_activated with its token, which dismisses crustace's splash.

• An app's own files in a browser: ltk::vfs and ltk::web::load_tree — vfs, through which ltk reads its themes, fonts and layouts, is public: read, read_to_string, read_dir, is_file and is_dir are the file system's natively and, in a browser, read the files the page loaded into memory. load_tree( base, root ).await loads any tree served with a MANIFEST, as ltk's resources are, under root, and load_resources is now load_tree into /ltk and that directory made the resource directory. crustace loads its catalog of applications and their icons this way. In a browser the activation tokens an app asks for with App::take_activation_requests are now issued: forge/web's, through its activation_token request, or empty without a desktop, as on Wayland without xdg-activation, handed to App::on_activation_token and their messages processed before the app draws. Before, a browser app that launched others through tokens waited for one that never came.

• The shell protocol in a browser: ltk::web::shell_send and ltk::web::set_shell_listener — a shell such as crustace speaks to forge over a socket in JSON; on a page with forge/web the same JSON travels over the app's connection to it, shell_send( json ) as a shell request and each shell event's message to the listener set_shell_listener gives, as JSON. What is sent before the app has connected is sent once it has, so a shell can tell forge/web its theme while it starts. An overlay's role now carries its App::overlay_namespace, as its layer-shell namespace does on Wayland, so forge/web can tell crustace's launcher and Quick Settings apart.

• scripts/wasm-bindgen-cli.sh TOOLS_DIR — builds wasm-bindgen-cli into TOOLS_DIR/bin at the version of the wasm-bindgen crate ltk pins in its Cargo.toml, from its sources with a lock resolved for Debian's rustc, which is what make web-deps did inline. make web-deps runs it, and since make install copies scripts/ into the registry, a project that builds for the browser against the installed ltk, such as forge/web or crustace, gets the same CLI without a checkout of ltk.

• ltk::time::Instant — ltk's monotonic clock, std::time::Instant natively and web_time::Instant on wasm32, where std::time::Instant::now panics, so an app that also builds for the browser measures time with the same clock as ltk and as osk::Panel::press_down, which takes it.

• A browser app joins the page's desktop — on a page where forge/web has published globalThis.forgeWeb, the web backend connects to it as the app's app_id and asks for its main surface in the role the app's hooks give (shell_mode, layer_anchor, layer_size, exclusive_zone, keyboard_exclusive, window_size_hint), as a Wayland compositor would read them; it draws into the canvas forge/web gives, listens on the input element above it, takes its size and scale from forge/web's configure, sends its input region when it changes, and leaves the keyboard focus to the desktop. A close reaches App::on_close_requested, and on exit the surface is destroyed and the connection closed. The app's overlays become surfaces of the desktop as App::overlays() changes, layer surfaces or, for Layer::Window, windows, with their sizes and zones in logical pixels and an update_role when one changes; forge/web's close of one delivers its on_dismiss. Popups anchored to a widget and the tooltip wait for a popup role. What every backend does as overlays come and go, resolving an OverlaySpec::size and moving a drag and the focuses off an overlay that goes, moved out of the Wayland backend into event_loop/overlays.rs (AppData::overlay_size, AppData::remove_overlay). The app's subsurfaces become surfaces of the desktop too, each sized to its parent and taking no input, painted on one shared GPU canvas only when it appears, its size changes or its content_version does, and otherwise moved with an update_role, which the browser composes without painting; App::on_subsurface_committed follows each paint, and while the app animates by subsurface motion only (App::subsurface_motion_only) a parent's frames keep coming without painting it. Painting a view on a canvas with no focus, hover or press, which both backends' subsurfaces do, moved out of the Wayland backend into draw::paint_detached. A lost WebGL context now drops the overlays' and subsurfaces' GPU canvases too, not only the main surface's. examples/web_shell.rs is a shell for the desktop, a background with a bar in the top layer, a panel that takes the keyboard and a card on a subsurface that slides. A page without a desktop, or one that named a canvas with set_canvas, runs the app as before. The new RunError::Desktop says forge/web refused the main surface. Every surface now paints through the app's one WebGL2 context, on an OffscreenCanvas, and its frame moves to the surface's canvas, a bitmaprenderer, as an ImageBitmap: a page holds few WebGL contexts, and a desktop's apps have many surfaces.

• Browser backend, the web feature — ltk::run on a page's canvas, built for wasm32-unknown-unknown with wasm-bindgen, js-sys and web-sys, optional dependencies on that target only. build.rs refuses it with another backend or for another target, so a web build uses default-features = false, features = [ "web" ]. A page's main thread must not block, so run sets the app up and returns, and setTimeout and requestAnimationFrame drive the loop; Sources (event_loop/sources.rs) gains a queue of timers and channels for it, and page events and ChannelSender::send only queue and schedule an iteration. The app draws on a canvas laid over the whole page, or the one ltk::web::set_canvas gives, through WebGL2 with the GLES canvas unchanged, or without it in software through putImageData; its logical size is the canvas's CSS size, its scale the page's devicePixelRatio, fractional as it may be, so the canvas holds the display's own pixels. Panics go to the browser's console. When the app exits, the canvas receives an ltk-exit event. The new RunError::NoDocument is returned where there is no page, as in a worker. The built-in keyboard serves text where the page is used by touch. Input comes from the canvas's Pointer Events, a mouse as the pointer and fingers and pens as touches, at offsetX / offsetY in CSS pixels; a press captures the pointer and focuses the canvas. A wheel in lines scrolls in detents, one in pixels continuously, and the page neither scrolls nor zooms under the canvas. Keys take their keysym from KeyboardEvent.key, their code from .code as the Linux input code Wayland reports, and repeat on the browser's clock; AltGr types its character rather than counting as Ctrl and Alt. ltk takes every key the browser gives a page, and while fullscreen also those navigator.keyboard.lock() gives where there is one. The cursor's shape is the canvas's CSS cursor, and on macOS Command counts as Ctrl. Copies go to navigator.clipboard.writeText; a page reads the clipboard only from a paste event, so Ctrl+V is let through to the browser and held until its paste has put the text in AppData::clipboard, and a paste from the browser's menu comes as a Ctrl+V of its own. A lost WebGL context drops the GPU canvases and draws nothing until it is restored, on a new glow::Context, so the glyph atlas and the caches of the old one are not reused. On ltk's own canvas the page's env( safe-area-inset-* ), read from a hidden element, become the main surface's insets. Resources are the tree an Android package carries, which scripts/web-assets.sh builds through android-assets.sh and make web-assets builds into target/web/ltk/ with the in-tree default theme and the fallback fonts WEB_FONTS names; ltk::web::load_resources( base ).await fetches its MANIFEST and every file it lists, with the manifest's hash in their URLs so a changed tree is not served from the browser's cache, into memory under /ltk, which becomes the resource directory. The per-script fallback fonts are now read through resources::read_font, so a path that does not exist is found by file name in the resource directory's fonts/, which is where a page's are. wasm-bindgen-futures joins the web feature. examples/web_hello.rs is the smoke test: make web-check typechecks the backend, make web-example builds the example and runs wasm-bindgen into target/web/, make web-serve serves it, and make web-deps installs Debian's std for wasm32 and wasm-bindgen-cli at the version of Cargo.lock. The text-scale watcher does not run in a browser, and the built-in keyboard's language is the page's. Not yet: overlays, secondary surfaces and subsurfaces, dead keys and input methods, the accessibility tree, the primary selection, and a canvas that changes size while the window does not.

• The built-in keyboard serves an app's own text input — while App::external_text_input asks for text and no ltk text field has the focus, the built-in keyboard shows with App::external_text_purpose (a terminal gets its row of Escape, Tab, Ctrl, Alt and arrows), comes back when the serial changes, and hides when the request ends. Its keys reach the app as physical ones, pressed and released through App::on_raw_key_event with the panel's Ctrl and Alt held for them. Before, the built-in keyboard only served ltk's text fields, so such an app had no keyboard where the compositor offers no input method.

• Android: the system clipboard, back that leaves, ltk's keyboard, HOME and LANG — copies go to Android's ClipboardManager and its text is read back whenever the app gains the focus, through JNI on the activity (the jni crate joins the android feature). Back with nothing left to go back to minimises the app with moveTaskToBack, or closes it, as App::back_at_root says; the new Platform::back_leaves decides whether back may leave the main surface, which keeps Wayland's rule of the xdg-toplevel. Text is typed on ltk's own keyboard rather than the system's, from which a NativeActivity gets only key events. set_android_app sets HOME to the app's internal storage and, unless set, SSL_CERT_DIR to Android's CA certificates and LANG to the device's language, so desktop code finds its preferences, a TLS client its roots (rustls-native-certs knows no Android path) and the locale.

• Android: running in the background and closing — ltk::keep_running( Some( text ) ) starts the keep-alive service of an APK packaged with KEEP_ALIVE=1, a foreground service with text on an ongoing notification, so Android does not freeze the app once it leaves the screen; None stops it, and without the service nothing happens. When the app's last surface closes, ltk calls finishAndRemoveTask and waits for the activity to be destroyed: a second activity that Android starts in a process whose android_main returned never comes up, so the app should end the process after run returns rather than wait to be started again. set_android_app sets up the process only on its first call and keeps the latest activity on every call.

• ltk::resource_dir() — the resource directory set_resource_dir gave, so an app finds its own bundled files (a terminal's monospace face) among the resources unpacked from the APK. make install now copies scripts/ and java/ into the registry, so apps package with the installed android-apk.sh and android-assets.sh.

• Surface insets — SurfaceState::insets holds the logical pixels the system covers along each edge of a surface; the view is laid out inside them while the background still fills the whole surface, and positions stay absolute, so hit testing is unchanged. The built-in keyboard is placed inside them too. On Android 11 and later they come from the window's getRootWindowInsets(): the status bar and any cutout on top, and on the other edges only bars that take taps, so gesture navigation leaves no gap at the bottom while a bar of buttons keeps its room; earlier releases fall back to the activity's content rect. On Wayland they stay zero.

• APKs with Debian's own tools — scripts/android-apk.sh OUT.apk LIB.so PACKAGE LABEL [ASSETS_DIR] packages an app built as a cdylib into a NativeActivity APK: it writes the manifest (the library loaded as libmain.so, optional permissions, a theme without an action bar, which the content rect would otherwise leave room for), compiles it with aapt against android-framework-res, adds the assets and the library, aligns with zipalign and signs with apksigner, creating a debug keystore in ~/.android/ when there is none; no Gradle or Android SDK download is involved. ICON gives the launcher icon, an SVG rasterised with rsvg-convert for every density, or a PNG. KEEP_ALIVE=1 adds the only Java code, java/net/liberux/ltk/KeepAlive.java, compiled with javac and dx (art-standalone) against the platform 34 android.jar (google-android-platform-34-installer), which aapt then links against too, as Debian's framework-res predates the specialUse service type; the service is declared with KEEP_ALIVE_USE as its reason, with the permissions it needs. examples/android_hello.rs, a counter built as a cdylib only with the android feature, is the smoke test: make android-apk builds and packages it with the in-tree default theme, make android-install installs it through adb. On Android, set_android_app now also sends standard output and error, panics included, to logcat under the process's name.

• ltk::set_resource_dir( dir ) — an app's own copy of ltk's resources, for a package with no system to install them into. Its themes/ is searched after the user's themes and before /usr/share/ltk/themes, and its keyboards/ before the system's layouts; a font a theme names by an absolute path that does not exist is read from its fonts/ by file name, so a theme written against Debian's font paths works unchanged from the bundle.

• Themes and fonts in an Android package — set_android_app unpacks assets/ltk/ into the app's internal storage and uses it as the resource directory. assets/ltk/MANIFEST lists the tree, one path per line, since the asset manager cannot list subdirectories; the tree is unpacked again only when the manifest changed, and its first line is a hash of the contents. scripts/android-assets.sh builds the tree from installed themes, without their cursors, and copies the fonts each theme.json names and ltk's keyboard layouts (KEYBOARDS_DIR overrides where they come from); make android-assets runs it on the in-tree default theme. On Android the per-script fallback fonts are read from /system/fonts, and the primary face is the embedded Sora. make android-check typechecks the Android backend with Debian's own rustc, rust-src and google-android-ndk-r27c-installer, through -Zbuild-std; NDK, ANDROID_API and ANDROID_TARGET override its defaults.

• Android backend, the android feature — ltk::run inside a NativeActivity through android-activity 0.6 and ndk 0.9, optional dependencies that build only for Android targets. The feature excludes wayland, and build.rs refuses both at once, so an Android build uses default-features = false, features = [ "android" ]. The app's android_main passes its AndroidApp (re-exported as ltk::AndroidApp) to the new ltk::set_android_app before ltk::run; without it run fails with the new RunError::NoAndroidApp. The backend draws through EGL on the activity's ANativeWindow, with eglSwapBuffers waiting for the display, or in software into a locked window buffer; sizes the main surface to the window at the display's density in whole multiples of 160 dpi; turns fingers and styluses into touches, a mouse into the pointer and key events into keysyms and text through the device's character map; and types on ltk's own keyboard. calloop's descriptor rides on the activity's ALooper, so the app's channel and timers keep working. Not yet: overlays, secondary surfaces and subsurfaces, dead keys from a physical keyboard and the activity's saved state. EglContext gains new_android, create_native_surface and release_current, and swaps with the interval its backend needs; EglSurface::egl_window and resize are Wayland's only. What a frame callback does is now the backend-neutral AppData::frame_presented, which both backends call. session_state.rs builds only with wayland, its only user, and so do the AT-SPI2 adapter's construction and action forwarding. The state only the Wayland backend reads moved out of the runtime's: the clipboard inbox, a drag's position and type, the first-configure latches (pending_fullscreen, pending_size_hint_unpin, pending_size_hint_fit, fitted_size_hint) and the overlay canvas pool from AppData into WaylandPlatform, and titlebar_base from SurfaceState into WaylandSurfaceState. A build with another backend does not warn about runtime code only Wayland drives; the Wayland build still does.

• wayland feature, on by default — the Wayland backend and its dependencies (smithay-client-toolkit, wayland-protocols, wayland-egl, wayland-scanner, calloop-wayland-source, and accesskit_unix for AT-SPI2 accessibility) are now optional. A new build.rs sets cfg( backend ) when some backend is enabled, which builds the runtime: run, try_run, RunError and everything behind them. With --no-default-features only the runtime-free core builds (UiSurface, widgets, layout, theming, rendering, EglOffscreenContext); EglContext and EglSurface need wayland. The backend in use is named by platform::NativePlatform and platform::NativeSurface. make install now copies build.rs into the registry. Builds with default features are unchanged.

• TextEdit::color( c ) / TextEdit::on_focus( msg ) — color sets the colour of the value, which always came from the theme; the placeholder keeps the theme's. on_focus emits a message when the field takes the keyboard focus (press, Tab, take_focus_request), once per change and not for a press on the field that already holds it. App::on_text_input_focused( bool ) only says that some text field is focused; an app that mirrors focus into another model (rustdroid keeps Android's focused view in step) needs to know which, and a per-widget message carries that without a WidgetId, which is a &'static str and cannot name a dynamic handle. The message rides the WidgetHandlers::TextEdit snapshot and is pushed from set_focus.

• External text input: App::external_text_input(), on_external_text_commit, on_external_text_delete — lets an app hold the input method for a text field ltk does not own: an editable inside an embedded web view, a guest toolkit's field. While external_text_input returns Some( serial ) and no ltk text widget has the focus, the runtime keeps a zwp_text_input_v3 enabled, so the compositor raises its on-screen keyboard, and routes commit_string / delete_surrounding_text to the two new hooks instead of to a widget; a change of serial renews the enable, which is how a host asks for a keyboard the user folded to come back. Polled after every batch of updates through AppData::sync_external_text_input; an ltk text widget that takes the focus wins and hands the text-input back when it loses it. Keys such as Backspace and Enter keep arriving as key events. Default None.

• App::on_back() / BackResponse — the app's answer to a back request (the shell's back button or gesture, delivered as XF86Back, or a mouse's BTN_SIDE / BTN_BACK). Back peels one layer per request: transient UI the runtime owns (xdg-popups, context menu, text selection, a dialog's on_escape), then text-input focus, then on_back, then on_key_with_modifiers( XF86_Back ) for apps that bound the key themselves, then back_at_root. BackResponse::Message carries the message that undoes the top-most piece of navigation state, Consumed is for hosts whose back stack lives elsewhere (an embedded Android runtime), Unhandled means the root. Default Unhandled.

• App::back_at_root() / BackAtRoot — what back does with nothing left to go back to: Minimize (default; xdg_toplevel.set_minimized, the app and its state stay alive), Close (through on_close_requested) or Ignore. Only ShellMode::Window surfaces react; layer-shell and session-lock surfaces never do.

• NavStack<R> — navigation state for an app made of screens, kept in the app's model: push / pop / replace / pop_to_root / reset / current / iter, never empty, serialisable whenever R is. back( msg ) answers on_back, and persisting the same value from save_state makes back retrace the same screens after a session restore.

• docs/navigation.md — the navigation-state model: transient UI versus navigation state, the back order and its rationale, why the answer is derived instead of recorded, how it lines up with save_state, embedded web views, foreign back stacks, and an author's checklist. architecture.md, onboarding.md and the cookbook's multi-screen and session-state recipes point to it; the multi-screen recipe now uses NavStack.

• App::claims_raw_touch_at( x, y ) — per-press variant of claims_raw_touch: a finger landing where the app returns true rides the raw on_touch_* stream through the auxiliary-slot path and clears the widget focus, while fingers landing elsewhere keep driving the gesture machine. Lets an app embed a self-contained input consumer (a WebView) next to regular widgets. Only consulted for the main surface; default false.

• App::fullscreen() — desired fullscreen state of the toplevel at runtime, polled after every batch of updates; a change is forwarded as xdg_toplevel.set_fullscreen / unset_fullscreen. The built-in titlebar is not painted while the compositor reports the window as fullscreen. Default None (window state left alone).

• PatternGrid::size( impl Into<Length> ) — explicit side for the square grid, resolved through Canvas::resolve_geom like the other geometry overrides; without it the theme's fluid default still applies. A lock screen can now size the grid from the surface (a share of the width in portrait, of the free height in landscape) instead of being capped at the default.

• xdg-session-management-v1 (client) — before the first commit of a ShellMode::Window toplevel the runtime binds xdg_session_manager_v1, issues get_session( reason, stored_id ) and restore_toplevel( toplevel, "main" ), so a supporting compositor restores window geometry on every launch. Bindings are generated in-tree from the vendored XML under protocols/ with wayland-scanner (src/protocol/).

• Runtime session persistence — $XDG_STATE_HOME/<app_id>/session.json (compositor session id, clean-exit marker, pid) plus state.bin (the bytes from App::save_state), written atomically with mode 0600; saved every 30 s when the bytes changed, on close and on signal; handed back through App::restore_state before the first frame only on a session restore (LTK_SESSION_RESTORE=1) or after an unclean exit. Module src/session_state.rs.

• Layer::Window overlays — an OverlaySpec with layer: Layer::Window is materialised as an ordinary xdg_toplevel of the given fixed size instead of a layer-shell surface: decorated, stacked and listed by the compositor like an application window. Anchor, exclusive zone and keyboard exclusivity are ignored; the compositor's close button delivers on_dismiss. App::overlay_title( id ) (defaulted to the app id) names it. Layer-shell apps now bind xdg_wm_base when available so they can open one.

• Clean exit on SIGTERM / SIGINT — the runtime installs a calloop signal source and leaves the event loop instead of dying, so save_state runs and ltk::run returns.

• Slider::on_release / VSlider::on_release — fired once with the final value when the drag ends, so an app can keep an expensive commit (a subprocess, a D-Bus round trip, a compositor reconfigure) off the per-motion on_change path and still move the thumb live. The gesture machine emits it from the slider branch of on_release; on_change alone behaves exactly as before.

• Viewport::local_viewport() — resolve the child's viewport-relative (vw / vh / vmin) and fluid Lengths against the viewport's own rect instead of the root layout viewport the sub-canvas inherits. For fixed-size floating mini-UIs (a phone-shaped panel pinned to a corner of a desktop-wide surface) whose content is calibrated against the panel rect; scroll-like clips should keep the default inheritance.

• ListItem::height( impl Into<Length> ) / ListItem::font_size( impl Into<Length> ) — override the theme row height (floored at the label's rendered height so text never clips) and the primary-label font size, mirroring the Toggle / Radio height() builders, so dense menus can trade the touch-target generosity for row density.

• Accessibility text scale — set_text_scale / text_scale global multiplier (clamped [0.5, 3.0]) applied to every resolved font size (Canvas::resolve_font and the stock-widget font_px path); geometry is untouched. The run loop reads org.gnome.desktop.interface text-scaling-factor at startup and follows external changes via a gsettings monitor watcher thread, repainting on change — every ltk app tracks the desktop's "large text" setting live with no app-side wiring (silently fixed at 1.0 when gsettings is missing). Embedders driving core::UiSurface call set_text_scale themselves.

• Per-canvas pixel density — Canvas::set_density pins a canvas (and the sub-canvases derived from it) to its own density factor for Length::dp resolution, overriding the process set_density global; Canvas::density reads the effective value. New Canvas::resolve_geom / Canvas::resolve_font resolve an explicit Length in geometry / font space with the canvas' density — widgets now route caller-supplied lengths through them, so a dp override follows the canvas it draws on. The hook for surfaces on outputs whose DPI differs from the process-wide one (an overlay on a second monitor, an embedder with several UiSurfaces).

• Length::resolve_with_density — Length::resolve with an explicit density for LengthBase::Dp, instead of the process density().

• docs/backends.md — the canonical software/GLES capability matrix: what renders identically, what degrades gracefully on software (gradients, shadows, backdrop blur, bottom fade) and what is GPU-only, replacing per-method rustdoc archaeology. Linked from README, onboarding and the architecture known-gaps list.

• Clippy in CI — the test job lints with cargo clippy --workspace --all-targets --features test-support -- -D warnings; make clippy mirrors the invocation locally.

• ListItem::trailing_icon( rgba, w, h ) — right-aligned icon slot (disclosure arrow) drawn at TRAILING_ICON_SIZE (21 px) and vertically centered, alongside the existing leading icon. Coexists with trailing text, which shifts to the icon's left. Symbolic icons should be pre-tinted by the caller (tint_symbolic), matching the leading-icon contract.

• ListItem::pad_h( impl Into<Length> ) — per-item override of the horizontal inset between the row edge and its content; without it the theme default (16 px) applies.

• Row::align_top() / Row::fill_height() — pin children to the row's top edge instead of the default vertical centering, or stretch every non-spacer child to the row's inner height (the row itself is still sized by its tallest child), for siblings whose natural heights differ by a few font-metric pixels.

• App::window_resizable() — return false to keep the min_size == max_size pin from window_size_hint for the toplevel's lifetime, declaring a fixed-size window compositors must not resize. Default true.

• App::claims_raw_touch() — return true to receive the primary finger through the raw on_touch_down / move / up stream, bypassing the built-in single-slot gesture machine entirely (widget presses, taps and swipes stop working on touch), for surfaces that are one self-contained input consumer such as an embedded WebView or a game canvas.

• Responsive sizing system with two selectable modes via WidgetScaling (Fluid / Physical; set_widget_scaling / widget_scaling, default Fluid). New Length constructors — orient( portrait, landscape ) (a percentage of the width in portrait, of the height in landscape), fluid( px ) (surface-proportional, calibrated against set_fluid_reference and bounded by FLUID_MIN / FLUID_MAX), dp( px ) (constant physical size scaled by set_density / density), and widget( px ) (picks fluid or dp per the active mode). Canvas::geom_px (geometry, physical layout space) and Canvas::font_px (font, bridging the logical / physical split per mode) give widgets and apps one resolution path.

• Button::font_size / height / width and TextEdit::height builders, all impl Into<Length>, so control boxes scale with the surface. Text::line_height( mult ) opens the gap between wrapped lines. Separator::pad_v (with Length::px( 0.0 ) for a flush divider).

• Performance guardrails: opt-in diagnostics via LTK_PERF_WARN=1 (stuck animation, sustained software-render animation, low poll_interval) and a ~30 Hz software-animation cap overridable with App::cap_software_animation.

• grid_min_cell( width ) and WrapGrid::max_columns( n ) — adaptive grid: the column count is derived at layout time from the available width so every cell is at least width wide (any Length; never fewer than one column), re-derived on every resize; max_columns caps the count so cells grow instead of multiplying on wide surfaces. grid( n ) keeps the fixed-count behaviour.

• Vertical flex: flex( child ) now distributes leftover height inside a Column, mirroring its leftover-width behaviour in a Row — weights split the spare space between flex / spacer siblings, the child draws inside the allocated share, and it contributes zero to the column's natural height like a weight-only spacer.

• make stylecheck / scripts/style-check.sh — mechanical checks for the grep-verifiable subset of the style guide (tab indentation, spaces inside attribute brackets), wired into CI. The whole tree was normalized to pass (82 attribute sites).

• ltk::orientation() / viewport_size() / set_viewport_size and the Orientation enum — the runtime records the main surface's physical dimensions on every configure, so view() can branch a layout on portrait vs landscape (match ltk::orientation() { … }) without tracking on_resize by hand; the portrait/landscape rule matches Length::orient (square counts as portrait). Embedders driving core::UiSurface directly call set_viewport_size themselves. examples/clip_path.rs demonstrates it.

• test-support Cargo feature gates the test_support module so third-party builds never see it (ltk's own make test enables it).

Changed

• A surface's scale may be fractional. SurfaceState::scale_factor is an f32, the physical pixels per logical one, which Platform::prepare_canvas, Presentation::scale and the paint path take as it is; a surface's physical size is its logical size times the scale, rounded once (physical_width, physical_height), and buffer_scale() gives the whole number Wayland's buffer scale and regions need. Wayland and Android still set whole scales, so nothing changes there; the browser backend sets the page's devicePixelRatio. App::on_scale_changed keeps its u32, the scale rounded, and App::on_resize gives the exact physical size.
• ltk::ChannelSender is ltk's own type instead of a re-export of calloop's Sender, with the same send, returning Result<(), std::sync::mpsc::SendError<T>>, and Clone, so apps that only send and clone it build unchanged; code that named calloop's type has to name ltk's. The runtime arms its timers and channels through event_loop/sources.rs instead of a calloop LoopHandle. calloop, khronos-egl and raw-window-handle are dependencies only off wasm32, where egl_context, UiSurface::try_new_gles, UiSurface::from_current_gles_loader and the native GL names of BorrowedGlesTexture (texture_id, framebuffer_id) do not exist; the monotonic clock is crate::time::Instant, which is web_time::Instant on wasm32, and chrono takes its wasmbind feature there.
• Themes, fonts, keyboard layouts and images are read through vfs.rs, which is the file system natively and on wasm32 a set of files held in memory, filled through vfs::insert. A wallpaper or an Image::from_path is now decoded from the file's bytes, so its format is told from its contents rather than its extension.
• Input reaches the runtime as platform-neutral events. input/event.rs defines KeyInput, PointerInput and TouchInput, and the pointer, touch and keyboard handlers take them through a small set of entry points (pointer_input, touch_input, key_press, key_release, key_repeated, modifiers_changed, keyboard_enter, keyboard_leave, set_repeat_info) instead of smithay-client-toolkit's events. The KeyboardHandler, PointerHandler and TouchHandler implementations moved to platform/wayland/input.rs, which only records the serials later Wayland requests need, resolves surfaces and translates. What input handling asks of the windowing system (window move, resize, minimise and fullscreen, a bare frame request, the cursor's shape, the input method) is done by named methods in platform/wayland/, so nothing under input/ names Wayland and no entry point or set_focus takes a QueueHandle; ResizeEdge is ltk's own. The protocol state moved out of AppData into platform::wayland::WaylandPlatform, held as AppData::platform, and the compositor, shell, seat and output handlers, the data device and the primary selection moved from event_loop/ to platform/wayland/. Each surface's Wayland half (SurfaceKind, the SHM pool, the EGL window surface and what the compositor was last told) moved from SurfaceState into platform::wayland::WaylandSurfaceState, held as SurfaceState::platform, and the requests above form the platform::Platform trait, with the surface type as its associated Surface. Drawing a frame is split from presenting it: draw/paint.rs paints a surface's view in full or under its dirty rects, the same for the software and GPU canvases, in place of the four near-identical paths of draw/software.rs and draw/gles.rs, and the backend prepares the canvas and presents it (Platform::prepare_canvas, present, precise_damage), in platform/wayland/present.rs, which also took the opaque and input regions and pick_shm_format. The EGL context moved into WaylandPlatform. Publishing the clipboard and the primary selection goes through Platform::publish_clipboard and publish_primary_selection, while their text stays with the runtime in AppData::clipboard and the new AppData::primary_selection. The runtime is generic over the platform: AppData<A, P: Platform = NativePlatform<A>> and SurfaceState<Msg, S = NativeSurface>, resolved at compile time; the backend-neutral half of a configure is SurfaceState::set_size and AppData::on_main_resized, and the backend-neutral half of a loop iteration moved from run.rs to event_loop/step.rs (process_messages, draw_due, and around them next_wakeup, before_draw and after_draw, which carry the deadlines, the clipboard inbox, the accessibility tree and its actions, and the app's blur, copy, paste and focus requests), with AppData::new and AppData::install_sources (event_loop/setup.rs) building the state and the event sources every backend has. The run loop itself, overlay and subsurface reconciliation, session management, output probing and window fitting moved from event_loop/ to platform/wayland/, with the main output, the subsurfaces and the drop inbox now in WaylandPlatform; AppData::secondaries pairs each surface with Platform::Output. Tests drive the runtime on platform/mock.rs, a platform that logs what is asked of it, through input, update, painting and presentation (event_loop/tests.rs). The behaviour is unchanged, but for a frame whose presentation fails, which now leaves the next frame to repaint in full. This is the first step towards backends other than Wayland, starting with Android; docs/architecture.md describes the events, their units and what stays with a backend.
• ltk::Keysym comes from xkeysym, the crate smithay-client-toolkit re-exported it from, so it is the same type and no code using it changes.
• XF86Back is no longer an alias of Escape. It used to run the Escape path: close transient UI, else drop the focus and reach on_key_with_modifiers. It is now a back request with its own order (see App::on_back under Added). Visible differences for an existing app: with a text input focused, back only drops the focus and the app sees the next request, where it used to get the key in the same press; the key is no longer reported through App::on_raw_key, so hosts forwarding raw keys into an embedded view stop leaking it to the page; it no longer auto-repeats by default (App::key_repeats); and a ShellMode::Window app that handles neither on_back nor the key is minimised on back at its root, where nothing happened before — return BackAtRoot::Ignore from back_at_root to keep the old behaviour. An app that binds XF86_Back in on_key / on_key_with_modifiers keeps receiving it. Escape itself is unchanged; its transient-UI step is now shared with back as AppData::dismiss_transient.
• A window_size_hint larger than the screen is shrunk to fit. The hint is pinned as min_size == max_size before the first commit, when no output is known yet, so an app asking for a phone-shaped 720x1440 window on a 1080p desktop got a toplevel taller than the screen. On the first configure the runtime now fits the hint, keeping its aspect ratio, inside the compositor's xdg_toplevel.configure_bounds (WindowConfigure::suggested_bounds) or, when it sends none, inside 90 % of the first output's logical size; min_size (and max_size for a non-resizable window) is re-pinned to the fitted size, which also replaces the hint as the fallback when later configures carry no size. A hint that fits is untouched. event_loop/window_fit.rs, with unit tests for the fitting rule.
• A press on a text field renews the text-input enable. Moving the focus between two text fields, or pressing the one already focused, used to commit only the refreshed content type on the existing zwp_text_input_v3. It now sends enable first, as GTK does when a focused entry is clicked: a compositor that folded its on-screen keyboard while the field kept the focus (the back button does) has no other way to learn that the user wants it again, since the text-input never stopped being active. ltk sends neither surrounding text nor a cursor rectangle, so the state enable resets is only the content type set right after it.
• The software backend's ARGB8888 conversion works on whole pixels. SoftwareCanvas::write_to_wayland_buf swapped red and blue with a byte-by-byte loop over the frame; it now reads each pixel as a u32, exchanges the two channels with masks and shifts, and lets the compiler vectorise it. Compositors that offer ABGR8888 were never affected.
• Breaking: App::app_id, App::save_state and App::restore_state are new mandatory trait methods — every implementor must add them (shell components: constant id, None, no-op). xdg_toplevel.set_app_id and the AccessKit application name now come from app_id() (previously "ltk" / "ltk-app"); the app_id element of the deprecated window_config tuple is ignored. Crate version bumped to 0.3.0.
• Button::icon_size takes impl Into<Length> and resolves through Canvas::resolve_geom, joining font_size / height / width. A bare f32 still means Length::px — every existing call keeps its exact size — but a caller can now pass Length::widget( n ) to have an icon button follow the widget-scaling mode the way stock icons do. Without it an explicit icon_size was the one geometry setter that ignored the mode, so a 21 px back arrow sat next to a list_item chevron that fluid sizing had grown well past 21 and looked visibly smaller.
• Length::dp now applies the density at resolution time, not at construction. The value carries its design pixels in a new LengthBase::Dp variant and resolve multiplies by the density in effect when it runs, so a set_density change takes effect on the next paint without rebuilding the view's lengths — previously a dp value was frozen to the density read when it was constructed. Behaviour is unchanged for code that sets density once at startup.
• The GLES image texture cache is now bounded to 32 MiB of estimated GPU memory with least-recently-drawn eviction (the in-use entry is never evicted). Previously it grew without limit for the canvas' lifetime, so a stream of distinct buffers (photo carousel, video thumbnails) could exhaust GPU memory.
• OverlaySpec::size is now ( Length, Length ) (was ( u32, u32 )), resolved against the main surface when the overlay is materialized; wrap existing sizes in Length::px( … ) for the old fixed behaviour.
• TextEdit::font_size, TextEdit::fixed_width and Separator::thickness now take impl Into<Length> (were f32), resolved like the button label (font space) / geometry space; the f32 sentinels are gone (f32 call sites still compile via Into<Length>).
• Dependency pins: fontdue = "=0.9.3" and ignore = "=0.4.23" are pinned exactly because newer releases require a rustc newer than the declared Rust 1.85 MSRV (Debian stable's toolchain).
• Renamed set_design_reference / design_reference → set_fluid_reference / fluid_reference. Length::dp changed meaning — it used to be a surface-proportional value, and that behaviour now lives on Length::fluid; dp is the constant-physical-size unit.
• Widget struct fields are now pub( crate ) (configured through builders), except the value / state types apps read or construct (Time, Date, ComboState).

Fixed

• A held button is not also tapped. A button with on_long_press and no on_drag_start stayed a tap after its hold fired, so releasing it sent its on_press as well; it no longer does.
• Drawing many small images no longer slows down as the image caches fill. Every hit in the GLES texture cache, the GLES surface cache and the software canvas's premultiplied cache looked its key up in a linear LRU order, so an app that draws thousands of small images, a terminal's glyphs in each of their colours, walked thousands of entries for each one on every frame. The caches now find, insert and evict an entry in O(log n), with the same budgets and eviction order.
• The cursor's shape over a browser app's overlays — the web backend set the CSS cursor on the main surface's element only, so over an overlay, such as crustace's dock or a panel, the pointer kept the page's arrow. Each surface now keeps the element that takes its input, the cursor's shape moves to that of the surface the pointer enters, and the last shape asked for is kept for it.
• A focus request reaches a widget scrolled out of view. Scroll viewports drop the widgets outside their visible area from the hit-test list, so App::take_focus_request for a text input that a tap had just added below the fold (a password field under the selected network of a Wi-Fi list) never found it — and the runtime kept re-requesting a rebuild and a redraw every frame while it waited. Widgets with a WidgetId that a scroll clips are now recorded with their content position (scroll_clipped); a request whose target is among them moves that viewport with the same rule keyboard navigation uses (scroll::offset_into_view) and is satisfied on the next frame. The wait is bounded to a few drawn frames, after which the request is dropped instead of spinning.
• Fast two-thumb typing no longer drops taps. A finger landing while another was still down went to the auxiliary slot and never reached the gesture machine, so on a touch keypad every overlapping tap was lost. A finger landing on a primary that is still a plain press (GestureState::is_plain_press: no drag, scroll, swipe or slider in flight) now commits that press as a tap at its last position and takes the primary slot; the earlier finger's release reports through App::on_touch_up. Presses that have become a drag keep the old behaviour, so a second finger during a pattern stroke or a slider drag still stays out of the gesture machine.
• PatternGrid::on_node fires once per node, not once per motion event. Every touch motion within a node's snap radius re-emitted the node's message and requested a repaint, so drawing a pattern rebuilt and re-rastered the surface at the touchscreen's motion rate. The gesture machine now remembers the node the finger is over (last_pattern_node) and emits only on change; a Slider move outcome without a message no longer requests a redraw.
• A tap on a button survives finger motion inside the button. Any travel past the slop turned the press into a vertical or horizontal drag and its release skipped the button, so a thumb that rolled on a large key lost the tap. While the pressed widget fires on press (WidgetHandlers::has_press) and the finger is still inside its rect, motion is ignored; the swipe machinery takes over from the original press point once the finger leaves, and presses inside a scroll viewport are unaffected.
• Gesture thresholds are logical pixels. The 8 px travel that turns a press into a scroll, swipe or drag, and the 6 px stray that cancels a touch long-press, were compared against physical coordinates, so on a scale-2 panel they were 4 and 3 logical px and an ordinary thumb tap became a vertical drag whose release skipped the button. SwipeConfig now carries the surface's buffer scale and the machine reads the thresholds through SwipeConfig::slop / stray.
• A 1:1 opaque image is a row copy in the software renderer. With the premultiplied copy cached, drawing it unscaled with no clip and full alpha now copies rows into the canvas instead of running tiny-skia's bilinear pipeline over every pixel, which is what a full-surface backdrop cost on every frame.
• The software renderer premultiplies an image once, not on every draw. SoftwareCanvas::draw_image_data converted the whole source to premultiplied alpha in floating point on each call, so a full-surface backdrop cost a pass over every pixel per frame on top of the blit. Premultiplied copies are now kept in a 32 MiB least-recently-drawn cache keyed by size, content fingerprint and alpha, the same key the GLES texture cache uses (fingerprint_rgba moves to render::helpers to be shared).
• Rows no longer spill their children out of the layout. Row distributed leftover width but had no notion of a shortfall: leftover floored at zero, so a cluster wider than its rect kept every preferred width and overflowed — symmetrically, since the no-spacer branch centres it, which is why both end labels of a segmented control were clipped at once. The shortfall now comes off the widest children first (water filling), so a long title gives up its width while the icon beside it keeps its size, and equal siblings — a segmented control — share it evenly; pinned spacers keep their width, and Row::no_shrink() opts out for strips deliberately wider than their viewport. Button elides its label into the rect it is granted, so shrinking degrades to a truncated label rather than clipped glyphs; the truncation rule moves to one crate-internal helper shared with ListItem.
• ListItem labels no longer run under the trailing slot. The label and subtitle were painted with no width limit, so a title longer than the row overlapped the trailing text or the disclosure icon instead of truncating. The trailing slots are now laid out first and both lines are elided with an ellipsis against the space they leave, matching what Text already did.
• Text inputs no longer insert mid-string when the value grows after focus. Focusing a text input pinned the cursor to a snapshot of value.len(); if the value kept growing without the widget seeing keystrokes (a field fed over IPC), the first normally-delivered key inserted at the stale position. The focus-time cursor is now an end-of-value sentinel that every consumer clamps to the current value length, collapsing to a concrete position on the first real keystroke or click.
• Single-line caret height now follows the text line. The caret spanned rect.height - 16, so a field taller than its text line grew an oversized caret; it now measures font_size + 4 and is vertically centered like the text, matching the multiline caret.
• Dialog action buttons no longer overflow the card on large surfaces. The card's width cap was a fixed 480 px while the stock buttons inside grow fluidly with the surface, so on windows past the design size the right-aligned action row ran off the card's right edge. Dialog::max_width now takes impl Into<Length> (f32 call sites keep compiling as fixed px) and the default is Length::fluid( 480.0 ), matching the buttons' scaling curve.
• App::on_pointer_axis now triggers a view rebuild and repaint. The raw axis hook (wheel/touchpad outside any ltk scroll viewport) fired the app callback but never requested a redraw, so state mutated there (a wheel-stepped carousel, an embedder-scrolled canvas) did not repaint until the next unrelated event.
• Dialog cards no longer double-pad their interior. The inner card column carried the column() 16 px default padding on top of the container's CARD_PADDING (24 px), giving the content 40 px of interior inset per side and squeezing the action row until its buttons clipped on narrow windows. The inner column is now flush and the interior inset is CARD_PADDING alone; the centering column's margin to the surface edges is explicit.
• Time-picker digits no longer overflow their boxes. The editable digit fields paired a fluid font (font_size_fluid) with a fixed 72 px box, so on any surface where the fluid font resolved larger than its design size the glyphs outgrew the field. The box is now Length::fluid( 72.0 ) — the same curve and clamp factors as the font, so both scale in lockstep.
• Content inside a scroll no longer renders smaller than the rest of the surface. Scroll viewports draw their child into a sub-canvas sized to the viewport rect, and fluid Length resolution (Canvas::geom_px / font_px — icon sizes, row heights, paddings, font sizes) resolved against that smaller canvas instead of the surface, shrinking everything inside any scroll by the width ratio (~13 % in a 360 px window with 24 px margins). Sub-canvases now inherit the root canvas's layout viewport (viewport_layout / viewport_logical), propagated through nested sub-canvases, so geometry resolves identically inside and outside offscreen content.

0.2.0 - 2026-06-25

This release adds the primitives an embedder needs to drive ltk as the render backend for a retained, externally-owned widget tree (for example projecting an Android view hierarchy onto an ltk surface). Each is kept general rather than tied to one consumer.

Added

• Canvas::set_clip_path — anti-aliased clipping to an arbitrary vector path (&[PathCmd]) on both backends. The software backend installs a tiny-skia coverage mask; the GLES backend captures the clipped draws into an offscreen layer and composites them back through an anti-aliased coverage mask. Complements the existing rect clip (set_clip_rects) for shaped clips such as a circular avatar, a rounded card or a VectorDrawable mask. See examples/clip_path.rs.
• Canvas::fill_path / Canvas::stroke_path over a new PathCmd command list (MoveTo / LineTo / QuadTo / CubicTo / Close, in surface coordinates) — renders an arbitrary vector path, a Path, a VectorDrawable or a Lottie frame. The software backend rasterises directly with tiny-skia; the GLES backend rasterises into a tiny-skia pixmap and uploads it, so both backends share the same path rasteriser and stay at visual parity.
• Canvas::read_rgba_pixels — reads any canvas into tightly packed straight-alpha RGBA8 (top-left row first), on both the GLES and software backends (the software path un-premultiplies its pixmap). Canvas::is_software lets a caller branch on the backend (e.g. honour a real path clip on software but only a bounding rect on GLES).
• measure_text( text, size ) (re-exported at the crate root) — measures one line with the default UI font and the system fallback chain, returning (width, line_height) in pixels without a live Canvas, for an embedder's measure pass that must match the renderer's metrics. Backed by a process-wide cached primary-font handle.
• Stack::push_placed — appends a child at an exact rect, bypassing alignment and intrinsic sizing, so a view tree whose geometry is computed elsewhere can be projected onto a Stack in paint order. Stack::push_placed_clipped additionally clips the child's subtree to a rect (Android's clipChildren): overflowing content is not painted.
• ExternalSource::Cpu and the External::cpu constructor — an immediate-mode CPU drawing closure invoked once per frame with the canvas and the widget's laid-out rect, working on both backends. Hosts a custom View.onDraw straight onto the ltk canvas without a GL texture round-trip, unlike the existing Texture source which only renders on GLES.
• RichText widget — wrapped paragraph text carrying a Msg per clickable link range; the layout pass emits one hit rect per link line so taps land on the link rather than the whole paragraph. The ltk side of an Android Spanned carrying URLSpan / ClickableSpan.

Fixed

• GLES clip-layer composite no longer renders path-clipped content vertically flipped: the offscreen layer was sampled at the inverted screen Y. The software backend was unaffected.
• Gesture: the horizontal pager is driven only once the swipe axis locks horizontal. Previously the pre-lock lateral drift of a vertical gesture could arm the consumer's pager without a matching release event, which could freeze the surface until an unrelated gesture reset it.
• Software/GLES parity: the software backend now snaps glyph pen positions and image destinations to integer pixels (rounding to nearest), matching the GLES backend. Previously it truncated, so text and 1:1 images could land up to half a pixel off between backends and sample ~1 px softer.

Changed

• Default theme launcher SVGs replaced with renderer-compatible versions.

0.1.0 - 2026-03-10

Added

• Initial release.