Skip to content

zgx 0.1.6

Choose a tag to compare

@wingleeio wingleeio released this 29 Oct 20:53
· 1407 commits to main since this release

A patch: Rust and Luau code builds as before (every API change since 0.1.5 is an addition, and zgx-desktop and zgx-gpu 0.1.5 build against this zgx). zgx-gpu and zgx-desktop now need zgx-cosmic-text 0.19.3, published with it. One behaviour changes, below with what to check: Windows input methods go through the Text Services Framework by default.

Changed: what to check in an existing app

  • Windows: input methods go through the Text Services Framework by default, not IMM32. Editors give input methods and text services (the emoji panel, dictation, the touch keyboard) a text store: they read the text around the caret, place candidates at the clause they convert, reconvert committed text in place and follow the editor's input mode, and each clause is underlined. To keep IMM32, an app calls Application::text_services(false), and a user sets ZGX_TSF=0 (ZGX_TSF=1 forces the framework on); a window where the framework does not start uses IMM32 (windows).

Added

  • Emission and occlusion maps in 3D scenes: Map::Emission colours the light a mesh gives off (multiplying its material's emission), Map::Occlusion dims the ambient light reaching each point (glTF's occlusion, not the sun's or a bulb's). glTF models bring theirs, and KHR_materials_emissive_strength. A scene without textures still binds none and costs what it did; DamagedHelmet with all five maps: 25 driver blocks, as with three.
  • Routing (zgx-script): ui.router { routes, scheme } keeps where an app is: named routes with :params (navigate by name, open by path), back and forward with the mouse's buttons and Alt+←/→ (⌘[ and ⌘] on macOS), deep links by scheme, and router.view showing each route. A modal, popover or menu can be controlled (open = function, on_close), so a modal route opens with its route and goes back as it closes (routing).
  • Reorderable lists (zgx-script): ui.each(list, row, { key, reorder = function(from, to) end }) makes rows the person drags into a new order (above or below a row, a line showing where) or moves with Alt+↑/↓, each a Tab stop told how to move and a keyboard move heard ("Moved Inbox to position 2 of 5"); it works with animate. TestApp::drag and TestApp::scroll drive drags and scrolling in tests (dynamic).
  • Lists that load as they scroll, and debounced states (zgx, zgx-script): ui.list { on_end = fn, end_distance = 200 } (View::on_end in Rust) calls fn as the list's end comes in reach, once each time and again once its rows grow, filling a short view by itself, with no script running while it scrolls; ui.paged(load(cursor) -> { items, next }) gives items, loading, status, done, error (a UiError), more() and reload(), keyed like ui.resource and cancelling a load superseded; ui.debounced(state, ms) follows state once it has settled, on one timer (state). A script node is also 16 bytes smaller (a list's rarely set options are boxed).
  • Handlers that await, and optimistic writes (zgx-script): ui.async(f) is a handler running f as a task each call (a save on a click, a toast's Undo), cancelled as its owner goes, an uncaught error reported once. ui.optimistic(state, next, save) writes next now, keeps it if save succeeds and puts back what it replaced if not, returning the error; overlapping calls never revert over a newer write (state).
  • A 3D texture decoded from a file keeps the file, not its pixels: Texture::decode holds the PNG or JPEG and its decoded pixels only until a renderer has uploaded them, decoding again only if another upload needs them (a lost device, another window's renderer). Uploads share the decoder's pixels and build mipmaps without copying the full-size level. DamagedHelmet's live heap: 64.8 → 17.2 MB.
  • A failure is a typed error, not only text (zgx-script): ui.try's error, a promise's error, :after's on_error and what :await() raises are a UiError with message, kind ("raised", "action", "network", "cancelled", "http", "io"), an HTTP failure's status and body, and a raised value kept as value. ui.fetch(url, { raise = true }) rejects a status outside 2xx as an "http" error. It is still text: tostring, .., {err}, string methods, a state set to it, a toast's title/body and props read its message. Code comparing it with == to a string, or checking type(err) == "string", should read err.message or err.kind; under strict types, a state of strings is set to err.message (state).
  • Forms filled from what is loaded (zgx-script): ui.form { values = state } fills a form from a loaded record and follows it, a field the person has edited keeping what they typed; a form and its fields have dirty; submit and on_success are handed the form. Checkboxes, sliders, steppers, segmented controls and selects can be controlled as React's are (value = function, on_change). response.json is typed any and form.reset takes any record. TestApp::fill(id, text) replaces a field's text. The settings example shows them together (forms).
  • Decoding a PNG or JPEG holds about the image once, not twice: zgx_gpu::assets::decode_image decodes into the image's final buffer, widening RGB and grey to RGBA in place, rather than into a buffer the image was then copied out of. A decode's peak: PNG 2.00 → 1.09 images, JPEG 2.00 → 1.36 (zune-jpeg's own colour planes). For ui.image and 3D textures alike; under the system allocator, fewer freed large regions kept (a 3D model's three 2048 textures: 35.6 → 23.6 MB).
  • Normal and metal-roughness maps in 3D scenes: World::set_map(id, Map::Normal | Map::MetalRoughness, texture) (zgx-3d; Map::BaseColour is set_texture's). A normal map tilts a surface by its texels (glTF's convention: +x along u, +y up the texture), its frame taken from the screen's derivatives, so meshes need no tangents. A metal-roughness map scales the material's factors (blue metal, green roughness). glTF models bring theirs, in Rust and in ui.model. A scene without textures still binds none and costs what it did.
  • Textures in 3D scenes: Texture (zgx-3d), made from RGBA8 pixels or a PNG or JPEG, and World::set_texture(id, texture) colour a mesh across its texture coordinates, mipmapped and filtered. glTF models bring their base colour textures, in Rust and in ui.model. A scene without textures binds none and costs what it did. GPU-view painters get zgx_gpu::viewport::texture_with_levels: a texture written by the CPU in place on a Mac with unified memory, never copied. A copy into a texture would keep some 160 MB of Apple's driver memory while copies come (3D scenes).
  • Localized messages (zgx::i18n): ICU MessageFormat messages from JSON locale files, the locale negotiated from what the app asks or the system's preferred languages, and each message followed, so a locale switch or an edited file updates only the texts that changed. Plurals and numbers come behind the i18n feature, dates behind i18n-dates, both off by default (on in zgx-run). In scripts, ui.i18n { dir = "locales", source = "en" } loads a directory of locale files (a bundle ships them), ui.t(key, args) is a message as text or a label, and ui.locale reads and sets the locale. Every widget's label takes a message or a state and follows it: tabs, selects, modals, menus and the other components name their parts in the current locale.
  • A window's glass and light or dark change while it shows: WindowHandle::set_glass(Some(glass)) replaces its glass (macOS's effect view behind the content, Windows 11's system backdrop) and set_glass(None) removes it. WindowHandle::set_theme(Some(appearance)) shows it light or dark whatever the system shows, title bar included, and None follows the system again. Both were fixed when the window was made.
  • Theme tokens as typed fields in scripts: ui.tokens.notes.wash is "$notes.wash", built from the applied theme, so an editor completes an app's tokens and luau-lsp checks them. zgx lint's unknown-token rule names a token nothing declares (a misspelled "$app.crad" read as transparent before).
  • A key binding can name a physical key: KeyBinding::code("Numpad1", modifiers, action) matches the key with that physical code (the DOM's KeyboardEvent.code) whatever the layout makes it, so the keypad's 1 is apart from the digit row's.
  • A select's options follow a state (ui.select { options = state }, Rust select_live): relabelled in place in a new locale, added and removed by their value.
  • glTF models in Luau: ui.model { src, fit } shows a .glb or .gltf in a 3D scene. It's read off the main thread and shows once read, fit scales it to that many units across, and it hears clicks and hovers as a group does. A changed file reloads the script, as an image does (3D scenes). It's zgx-script's gltf feature, on in zgx-run (48.5 KiB of a build for shipping).
  • Read-only shared state for plugins (zgx-script): ScriptHost::expose_shared_read(key, capability) lets plugins read and follow a shared key without writing it. A plugin's set, update, push and the rest on it, or binding it where it is written, is an error naming the key; the app's scripts write it as before (plugins).
  • glTF models in zgx-3d (its gltf feature): Model::from_bytes reads a .glb, or a .gltf whose buffers are inline; Model::from_bytes_with reads one whose buffers sit beside it. A model brings its default scene's node tree, its meshes' triangles (smooth normals made where a mesh has none) and its materials' metallic-roughness factors, blending and unlit. World::add_model adds it as one group, with its base colour, metal-roughness and normal textures. Emission and occlusion textures, animations and skins are not read yet. cargo run -p zgx-3d --features gltf --example model -- FILE shows one.
  • A plugins example and guide (zgx-script): examples/plugins, a task list two plugins extend with before/after, a replacement, a filter, an @app module override and a shared package, its host deciding what they see; plugins.md covers making an app hookable, hook = false, the trust model of Override, and ui.shared/expose_action. A ui.show's or ui.switch's element can now be replaced or filtered, and zgx check resolves @app/… and @app-original/… against the app's directory.
  • Shadows in 3D scenes: World::set_shadows(true) (zgx-3d), or shadows = true on ui.scene3d, makes the sun (the first directional light) cast shadows from opaque meshes, filtered soft at their edges. Off by default, it costs nothing. On, it costs a 2048 by 2048 depth map (16 MB) and a depth pass that's drawn again only when meshes or the sun move, not the camera. In the Luau demo, orbiting: +2% GPU and +0.7% CPU (3D scenes).
  • Clicking and hovering 3D objects: World::pick(point, size) (zgx-3d) says which mesh a point of the view's box shows, where on it and how far from the camera (Hit). It's found on the CPU from the meshes' triangles, so a world never picked costs nothing. In Luau, ui.mesh and ui.group take on_click(hit) and on_hover(over); a group hears its meshes', and a drag (orbiting) clicks nothing (3D scenes).
  • Input modes, as HTML's inputmode: View::input_mode(InputMode::Email) (Text, Decimal, Numeric, Tel, Search, Email, Url, None), EditorHandle::set_input_mode, and Luau's inputmode = "email", say what kind of text a field takes. It is a hint, never a check. On Windows it is the field's input scope (through the Text Services Framework, the default; not with ZGX_TSF=0 or text_services(false)), which the touch keyboard and input methods follow, and None shows no touch keyboard. Windows input methods also reconvert committed text in place (select it, press Convert or Hanja).
  • macOS: an opaque GPU view gets a layer of its own (GpuView::set_opaque(true)): where its box shows it whole and alone, the painter draws straight into a CAMetalLayer, and zgx no longer copies it into the window's frame. On an M5 Max the system's GPU power about halves, level with wgpu's own, for about 1–2 points more app CPU, about 4 more of the window server's (as wgpu's) and about 20 MB. It never makes the main thread wait for a drawable: a thread of the plane's own waits for its drawables. It shows every refresh at 120 Hz on an M5 Max and an M1 Max, 19 and 27 ms from a frame's start. A box moved, clipped, faded or drawn over goes back into the window's frame in the same transaction, so no frame shows the view nowhere. The extra CPU is macOS's own for presenting a CAMetalLayer, so it stays opt-in: views not marked opaque, and zgx-3d's, composite as before (GPU views).
  • Plugin hooks (zgx-script): a plugin adds before or after any element of the app's, or in its place, without a slot: ui.contribute { target = "#save", after = node }. A target is an id, a declared hook = "name", or a role and a name as the app writes them; private = true takes an element out of reach. Replacing needs Capability::Override, ScriptHost::expose_hook makes a target ask a capability, and what a plugin adds is described to assistive technology as the plugin's (plugin hooks).
  • Plugin filters (zgx-script): ui.filter { target = "#title", text = function(text) … end } passes an element's text, label, hidden, disabled, tooltip, a ui.each's or ui.list's items or its children's order through a plugin's function, again when what it reads changes; it needs Capability::Override (plugin hooks).
  • Module overrides (zgx-script): a plugin trusted with Capability::Override replaces one of the modules the app requires as @app/…: ui.override { module = "@app/components/card", with = "./card" }, the replacement reaching the original as @app-original/…. The replacement runs as the app's own code, so the grant is a trust grant.
  • Packages (zgx-script, zgx-run): ScriptHost::package("kit", dir), or zgx.json's "packages", lets an app require modules from a folder outside its directory, as @kit/… or through a .luaurc alias into it; read only, and plugins reach none. build::bundle brings the packages its zgx.json lists into the bundle.
  • Styled highlight spans: a text area's highlighter can set a weight, italics, a strike and a wash behind a range, as well as its colour (View::span_highlighter, EditorHandle::set_span_highlighter, and SpanStyle, built as SpanStyle::default().weight(600).italic() so later styles stay additive; Luau's highlight spans take weight, italic, strike and bg by name beside { from, to, color }). A line whose spans set a weight or italics is shaped with them, so its width, wrapping, carets and clicks follow what shows. Other lines are shaped as plain text, as before. Overlapping spans merge, so a code span inside bold text stays bold. This is enough for a Markdown composer's emphasis and inline code (styled spans).
  • Reserved shortcuts: a key the app reserves is its own whatever has the keyboard, before a focused web page or terminal sees it, as a browser keeps ⌘T and ⌘W from its pages: Application::reserved_shortcuts, WindowFactory::set_reserved_shortcuts, KeyBinding::reserved(), and Luau's ui.command { reserved = true } (ScriptHost::reserved_keys). Only the app's own commands can be reserved, not a plugin's; zgx lint's reserved-system-key flags an editing or system key reserved (platform services).
  • Replacing a font while the app runs: WindowFactory::replace_font(font) shapes the families font holds with it in every window from then on, in place of the font they had: their text measures, lays out and draws again (styling).
  • An accessibility audit: zgx_desktop::accessibility::audit::audit(&mut ui) checks the tree a screen reader gets of a mounted interface, headless and with no permission, and walks Tab through it: controls, images and dialogs named, controls workable, check boxes, tabs and sliders saying their state, alerts live, field errors given to a reader, every Tab stop reached and focus coming round. Report::to_json() is a line for agents and CI. zgx's own CI audits the gallery and the Luau examples with it, their toasts, menus, popovers, dialogs and field errors open (composition).
  • A popover or menu with no name is named by its trigger (aria-labelledby), as the trigger reads now (overlays).
  • macOS transparency checked in the process: WindowHandle::debug_composition() reports what the window server composites of a window (its opacity and background, its layers, the pixels it shows), with no screen capture; the transparency example's --composition mode checks it on macOS CI (validation).
  • An editor's own caret colour and width: View::caret_color / caret_color_when, View::caret_width, EditorHandle::set_caret_style, and Luau's caret_color (a colour or "$token") and caret_width on ui.input and ui.textarea. By default the caret still takes the text's colour and the app's width (Ui::set_caret_width).

Performance

  • Scripts set up and run faster (zgx-script): a script's VM makes only the ui modules, and anime, that it names (#956), so setting one up costs 1.53 M instructions, against 3.83 M in 0.1.5 (−60%). By exact instruction counts against 0.1.5 on Linux arm64 and x86, every script benchmark is faster, by 0.06% to 3.6%: mount −1.7 to −2.0%, the apps' interactions −0.08 to −3.13%, the Luau microbenchmarks −1.79 to −3.56%.
  • The Rust benchmarks are within ±0.04% of 0.1.5 on arm64 and ±0.09% on x86, the rest being where the C allocator places memory; zgx's own code is flat.
  • A localized message costs about what its template twin does: updating a text whose plural follows a count costs about 1–2% more than the same text as a Luau template string ("{count} messages"): +1.2% by default, +2.2% with zgx-script's i18n feature, which zgx-run turns on. #974 chooses the plural form by a lookup made as the message parses.

Fixed

  • Tab moves past a split's divider: the divider claimed every key, Tab included, so focus stayed on it in every split view.
  • An alert (Role::Alert) is assertively live without saying so, as ARIA's is; an unnamed image inside a button, check box, tab, menu item or other control is the control's, not a bare "image" to a screen reader.
  • Letter spacing in a scene whose text shaper takes no font (Scene::set_text_shaper) spaces that shaper's own advances and wraps them as the GPU shaper does; it measured grapheme cells instead.
  • A faded clip wholly outside a popup no longer panics the app (zgx-gpu). Drawing a fade's bands as one, its box was clipped to what the window draws and clamped into; a box entirely outside it (seen with a folding list in an out-of-window popover) left that box inverted, f32::clamp panicked on every frame, and after a run of contained panics the app quit. Such a box now has no bands there and fades item by item, as it did.
  • A key a web page or terminal leaves alone reaches the app's shortcuts: with a WKWebView, a WebView2 page or a Ghostty terminal focused, a menu item's key or a key binding the page didn't use did nothing (a terminal typed it), as a browser hands its pages' unused keys to its own menus.
  • An object a page posts (webkit.messageHandlers.zgx.postMessage({…})) reaches the app in a debug build on macOS; it aborted it.
  • A spring or tween between very far values settles (it overflowed and asked for frames for ever).
  • Removing a subtree stops its effects before the destructors of what it held write state, so they no longer run once more on removed nodes; removing a large focused tree no longer panics when a listener's destructor removes another node.
  • A missing image's error names the script line that asked for it.
  • A press outside a popover closes it and goes on to what it lands on (a button acts, a field takes focus, a parent popover's row acts); a nested popover closes on a press in its parent's panel.
  • A fade (fade_edges) fades what it holds as one, as CSS's mask-image does: stacked items no longer each fade on their own. A faded scroll copies its interior and repaints only its bands, instead of its whole view every move.
  • With devtools tracing on, remounts no longer grow its log: an effect dropped takes its trace name with it.
  • A panic that repeats every frame no longer ends the app (zgx-desktop): one in the window's frame, a popup's frame or the popup windows' update is contained in that piece, reported once (log and banner), and the piece skipped, keeping its last frame, until what it draws changes (then tried again at most once a second). Before, a contained panic that came every frame (a popup's fade bands, #950) reached the 20-a-second limit and the app quit with panicking repeatedly.
  • Decoded images and SVGs no longer stay for the process's life (zgx-script). Each src was decoded once and kept until its file changed, so a page of forty large images left ~80 MB behind after it unmounted. What a mounted node shows is still kept. Of the rest, the most recently shown stay within a budget (48 MiB by default, ScriptHost::image_cache(bytes)), so a reload or a page shown again is still instant. The others go as nodes showing pictures unmount, never per frame.

Crates: zgx, zgx-components, zgx-gpu, zgx-3d, zgx-desktop, zgx-script, zgx-run and zgx-ghostty-sys 0.1.6.