Repository navigation
zgx 0.1.6
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 setsZGX_TSF=0(ZGX_TSF=1forces the framework on); a window where the framework does not start uses IMM32 (windows).
Added
- Emission and occlusion maps in 3D scenes:
Map::Emissioncolours the light a mesh gives off (multiplying its material's emission),Map::Occlusiondims the ambient light reaching each point (glTF's occlusion, not the sun's or a bulb's). glTF models bring theirs, andKHR_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(navigateby name,openby path), back and forward with the mouse's buttons and Alt+←/→ (⌘[ and ⌘] on macOS), deep links by scheme, androuter.viewshowing 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 withanimate.TestApp::dragandTestApp::scrolldrive 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_endin Rust) callsfnas 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 })givesitems,loading,status,done,error(aUiError),more()andreload(), keyed likeui.resourceand cancelling a load superseded;ui.debounced(state, ms)followsstateonce 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 runningfas 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)writesnextnow, keeps it ifsavesucceeds 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::decodeholds 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'serror,:after'son_errorand what:await()raises are aUiErrorwithmessage,kind("raised","action","network","cancelled","http","io"), an HTTP failure'sstatusandbody, and a raised value kept asvalue.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'stitle/bodyand props read its message. Code comparing it with==to a string, or checkingtype(err) == "string", should readerr.messageorerr.kind; under strict types, a state of strings is set toerr.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 havedirty;submitandon_successare handed the form. Checkboxes, sliders, steppers, segmented controls and selects can be controlled as React's are (value = function,on_change).response.jsonis typedanyandform.resettakes 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_imagedecodes 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). Forui.imageand 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::BaseColourisset_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 inui.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, andWorld::set_texture(id, texture)colour a mesh across its texture coordinates, mipmapped and filtered. glTF models bring their base colour textures, in Rust and inui.model. A scene without textures binds none and costs what it did. GPU-view painters getzgx_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 thei18nfeature, dates behindi18n-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, andui.localereads 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) andset_glass(None)removes it.WindowHandle::set_theme(Some(appearance))shows it light or dark whatever the system shows, title bar included, andNonefollows the system again. Both were fixed when the window was made. - Theme tokens as typed fields in scripts:
ui.tokens.notes.washis"$notes.wash", built from the applied theme, so an editor completes an app's tokens and luau-lsp checks them.zgx lint'sunknown-tokenrule 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'sKeyboardEvent.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 }, Rustselect_live): relabelled in place in a new locale, added and removed by their value. - glTF models in Luau:
ui.model { src, fit }shows a.glbor.gltfin a 3D scene. It's read off the main thread and shows once read,fitscales 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'sgltffeature, 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'sset,update,pushand 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
gltffeature):Model::from_bytesreads a.glb, or a.gltfwhose buffers are inline;Model::from_bytes_withreads 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_modeladds 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 -- FILEshows one. - A plugins example and guide (zgx-script):
examples/plugins, a task list two plugins extend with before/after, a replacement, a filter, an@appmodule override and a shared package, its host deciding what they see; plugins.md covers making an app hookable,hook = false, the trust model ofOverride, andui.shared/expose_action. Aui.show's orui.switch's element can now be replaced or filtered, andzgx checkresolves@app/…and@app-original/…against the app's directory. - Shadows in 3D scenes:
World::set_shadows(true)(zgx-3d), orshadows = trueonui.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.meshandui.grouptakeon_click(hit)andon_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'sinputmode = "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 withZGX_TSF=0ortext_services(false)), which the touch keyboard and input methods follow, andNoneshows 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 aCAMetalLayer, 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 aCAMetalLayer, 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 anid, a declaredhook = "name", or a role and a name as the app writes them;private = truetakes an element out of reach. Replacing needsCapability::Override,ScriptHost::expose_hookmakes 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, aui.each's orui.list's items or its children's order through a plugin's function, again when what it reads changes; it needsCapability::Override(plugin hooks). - Module overrides (zgx-script): a plugin trusted with
Capability::Overridereplaces 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.luaurcalias into it; read only, and plugins reach none.build::bundlebrings 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, andSpanStyle, built asSpanStyle::default().weight(600).italic()so later styles stay additive; Luau'shighlightspans takeweight,italic,strikeandbgby 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'sui.command { reserved = true }(ScriptHost::reserved_keys). Only the app's own commands can be reserved, not a plugin's;zgx lint'sreserved-system-keyflags an editing or system key reserved (platform services). - Replacing a font while the app runs:
WindowFactory::replace_font(font)shapes the familiesfontholds 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--compositionmode 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'scaret_color(a colour or"$token") andcaret_widthonui.inputandui.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
uimodules, andanime, 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'si18nfeature, 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::clamppanicked 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'smask-imagedoes: 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
srcwas 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.