lib-ui

lib-ui architecture

Layers

kinogaki-ui is everything that needs no window or GPU: math (geometry), color, paint (shapes, tessellation, text layout and the glyph atlas; glyphs are filled by kinogaki-svg's exact-area MaskRasterizer), input, layout, containers and widgets, and the Kinogaki modules below. It compiles in parallel with wgpu and winit. kinogaki-ui-wgpu draws a frame's triangles and paint callbacks with wgpu and holds capture; kinogaki-ui-shell runs winit windows (one per viewport), input, clipboard and the App loop; a window reads and writes the system clipboard on a thread of its own, in the order asked, so putting tens of megabytes there never stalls it (OutputCommand::ReplaceText puts a text in place of another only while the clipboard still holds it: an app's copy made in full after a short one went there at once). The code began as egui 0.36.2 and is ours now (docs/HISTORY.md). Every crate forbids unsafe code except kinogaki-ui-shell, which denies it and allows it only in src/sys.rs: winit's current event loop shared with immediate viewports, and the Metal layer's presentsWithTransaction for jitter-free live resize. wgpu and winit are the platform layers, frozen as source with every other third-party crate in vendor/.

kinogaki-ui modules

kinogaki-properties

Data-only property schemas, with no UI dependency, so libraries without UI can describe their parameters. Schema<K> (the host's key type K) holds Items: Sections, headings and Fields. A field has a label, a Kind (number with Number: unit, hard range, soft span, speed, decimals and NumberStyle; vector; fields; color; choice; dropdown; toggle; text; path; node path; expression; name; info; value; button; buttons; chips; ramp), a Value, enabled with a reason, tooltip, search keywords, error and mixed flags, an optional Socket, a Trailing slot, and its Animation (static, animated, keyed or overridden: its value field's tint, ANIMATED, KEYED, OVERRIDDEN) with whether the host keys it (keyable). A renderer reports Edits<K>: changed keys (new values are in the schema), gesture start and finish, Actions (press, browse, pick, index, socket, trailing, key: an Alt+click on a keyable field's label, relative, lock) and the typing draft. Schemas hold no host state or callbacks; hosts rebuild them from their data and apply the edits. numeric reads typed numbers: bounded arithmetic, relative forms (*=2), length units with exact conversions, the field's own unit word.

kinogaki-dialogs

One builder (FileDialog::open/open_many/save/directory, filter, starting_directory, file_name, title, detached) and one call, present(done), which returns at once; done runs once with the chosen paths (none when cancelled) or an Error. The application stores the answer and wakes its UI (Studio's editor keeps one dialog open at a time).

• macos.rs: NSOpenPanel/NSSavePanel on the main thread, begun as a sheet on the key (or main) window, or modeless when detached; AppKit calls the completion block on the main thread. objc2's bindings are safe here: no unsafe code.
• windows.rs: IFileOpenDialog/IFileSaveDialog on a thread of its own (a COM single-threaded apartment) owned by the active window, through raw vtables and system functions declared in the file. The crate denies unsafe code (instead of the workspace's forbid) and allows it only in this module; every block carries its safety argument. Written but not yet compiled or run on Windows.
• unsupported.rs: Linux and the rest answer Error::Unsupported until an XDG portal backend is written.

Style tokens

Every value shared by more than one widget or application is a Theme constant in crates/ui/src/theme.rs. Use the token, never its number: the editor's reference captures check that the look stays pixel-identical, and a token change is a deliberate visual change. Geometry that belongs to one widget (a marking column's width, the browser's 190-point category column, shelf padding) stays a named constant in that widget. Sizes are in points, and one point is one art pixel (see Pixel art below). The user's element size (set_element_size, Settings ▸ Interface in the editor) scales rows, buttons and fields: icon_button(), interact_size() and the row heights, their defaults times 85–125% (ELEMENT_SIZES, 5% steps) in whole art pixels. It is per thread (the UI thread's), read from Theme by every widget. Type and icons keep their pixels.

Colors (sRGB). The neutral ramp goes from dark to light; the accent marks selection and the active item. Ink on a fill comes from Theme::ink_on(fill) (dim_ink_on for disabled or secondary ink): black on a light fill (the accent, ACTIVE, any color black contrasts with better than TEXT, by WCAG contrast), TEXT on a dark one. Every widget's text and icons on a fill ask it, so they never disagree; accent-colored text on a dark background is not ink on a fill and keeps its color.

Corner radii (points).

Spacing and sizes (points).

Type. One face, MEK Sans, drawn on its 15-pixel em (pixel::FONT_PIXELS), with the platform's monospace face (Menlo on macOS, Consolas on Windows, DejaVu Sans Mono on Linux; the bundled fonts in crates/ui/fonts/ after it) for the glyphs it lacks.

Pixel art

The whole interface is drawn on a grid of square art pixels, one point each (2 × 2 physical pixels on a Retina-class display). Layout and input are in points. The context draws at one texel per art pixel (hosts report every display scale through pixel::pixels_per_point, which keeps it and answers 1; input conversion keeps the display's), and the shell's painter and the capture harness scale the frame up with nearest-neighbour sampling (kinogaki_ui_wgpu::pixel::Upscale::compose, which the capture harness's offscreen frames use too). Application content stays at the display's resolution: meshes textured with a user texture (a 3D view's render, an image) and paint callbacks are drawn straight onto the target at its scale, in paint order between the scaled-up interface layers (what is drawn over them, such as viewport overlays, is blended over as pixel art); applications size that content with pixel::content_pixels_per_point. Text is drawn at whole multiples of the pixel face's em (pixel::font_size), whatever size a widget asks for, with the pen on whole pixels and no line gap. The tessellator draws without feathering, with square corners (rounded rectangles leave their corner pixels out) and strokes at least one art pixel wide; glyphs and icons are rasterized with coverage on or off. pixel::snap, pixel::line_width and pixel::outline put a widget's own drawing on the grid. Letter spacing snaps each gap to whole art pixels before accumulating positions, including the gap before a truncation ellipsis, so fractional tracking cannot alternate between different gaps in uppercase section headings.

Widget contract

Widgets are immediate-mode functions over MenuItem { label, icon, family, unavailable, accent }; an empty icon shows the label alone (menus, the browser, marking menus), moved to where the icon was. Consecutive items with the same family form a group. An item with an unavailable reason is drawn muted, explains itself on hover and is never reported as chosen. Each widget returns the chosen index and the rectangles it drew, which applications use for pointer routing and interaction tests. Widgets hold no application state; persistent navigation (the browser's query, category and cursor) lives in a small state value owned by the caller. Proportions, radii and colors come from Theme, so applications look alike without restating them.

Every typed field (a number, a line of text, a rename) ends its edit one way, Response::edit_ended: Enter, Tab or a click elsewhere applies what was typed, and Escape drops it. Nothing applies while typing, so typing 1000 never applies 1, 10 and 100 on the way. Numbers read typed text with numeric::evaluate (arithmetic and units); a field with units of its own, such as a timeline's frames, gives its parser. A rename applies its name trimmed, and one left blank keeps the old name. The Escape that ends typing is that edit's alone: it is gone from the input (Memory::escaped says whose it was), so nothing under the field acts on it, though a dialog, the browser or the settings window whose own field it was closes on it. Search and filter fields apply as they are typed, and show no hint text.

Tests

crates/ui/tests drive widgets headlessly through kinogaki_ui::Context::run_ui with real input events: docking identity, numeric parsing and editing, icon layout, marking menu choice and bounds, browser navigation/search/dismissal, shelf tabs and tiles, card controls, and the consumed dismissing click of the menu bar and combo popups. Studio additionally renders these widgets through its offscreen GPU harness and compares captures pixel for pixel when they change.