Skip to content

zgx 0.1.7

Choose a tag to compare

@wingleeio wingleeio released this 01 Nov 20:29
· 1144 commits to main since this release

A patch: Rust and Luau code builds as before, but for a struct literal of PaintExtras or of zgx-desktop's WindowOptions (each has new fields) and code naming switches::ALL's length, each below with what to change. Every published 0.1.6 crate builds against this release. zgx-terminal is new: terminals on every platform, through zgx-desktop's terminal feature. Forks published with it: zgx-alacritty-terminal 0.26.0 and zgx-zune-jpeg 0.5.15 (new), zgx-cosmic-text 0.19.7 and zgx-mlua 0.12.6. Behaviours change too, each below with what to check.

Changed: what to check in an existing app

  • A covered window stops drawing on Windows (zgx-desktop): as on macOS and X11, a window nothing of which can be seen, or on another virtual desktop, does no drawing, and ui.window.shown is false there; on the way its menus and popovers close, as they do when it is minimized. A window that may show through (translucent, click-through, acrylic) never counts as covering it. Automated tests that need a covered window to go on drawing set ZGX_RENDER_WHEN_COVERED=1.
  • A selection is one rounded shape (zgx): text selections, in selectable text and editors, draw lines that touch as one continuous shape, with rounded outer corners and curved inner ones, even in a translucent colour and at fractional scales. $selection.radius is now 3, not 0; set it to 0 for plain rectangles. An empty line in a selection shows as a sliver. An editor's selection is one node carrying a highlight, not a rectangle a line, so code that walked an editor's nodes for them finds it through Scene::text_highlight.
  • zgx inspect and zgx test act only on what shows (zgx-script): a closed popover's, menu's or modal's content stays in the scene, unseen, and click, hover, right-click, drag, scroll, snapshot and wait took it as if it showed, landing on whatever was under it. They now fail with doesn't show … (open what holds it first); find and tree still list it, marked hidden. A test that clicked something closed now fails where it used to pass.
  • zgx-terminal's screen model is zgx's fork, zgx-alacritty-terminal (zgx-terminal): alacritty_terminal 0.26.0 without its comparisons of usize and i32 with its grid indices from the primitive's side. Those impls reach every crate linking it, where an inferred comparison (range.contains(i) with i: &&usize) stopped compiling: an app turning on zgx-desktop's terminal feature would have found code of its own broken. Its default serde feature is off.
  • A value the app sets on a ui.input or ui.textarea leaves nothing to undo (zgx-script), as setting an HTML field's value does: ⌘Z after showing another note could write the old note over it, and on_change would save that. The field's own edits still undo. A value answering one keeps the history: with value = function, the function's next change after on_change or on_commit, however late; with value = state, a different value within 100 ms of the edit. Rust's bindings keep their history (TextEditor::load_next asks for this).
  • An effect's run owns what it makes (zgx, zgx-script): a ui.on_cleanup, ui.after or ui.every made in a ui.effect now goes before the effect runs again, and with the effect, as the docs said and a React effect's cleanup does. Before, a run's cleanups and timers went to whatever was being built at the time, or to the script until it reloaded: content a ui.presence swapped out kept its effects' cleanups, and an effect's cleanups didn't run between its runs. A ui.computed run owns what it makes until its next run (start timers in an effect or a handler). Runtime::own and Runtime::running let a host give a resource to the running effect.
  • Edge fades ease in (zgx-gpu): fade / fade_sides (Styled::fade_edges) bands follow smoothstep rather than t². t² reached full opacity still rising, and the band's inner end showed as a line; smoothstep is level at both ends. Every fade looks a little different: content stays nearer full opacity further into the band and falls more steeply in its middle. Before and after: docs/results/fade-smoothstep-2026-10-31/.
  • The renderer going on with less stays out of release banners (zgx, zgx-desktop, zgx-script): a layer drawn coarser, an image softer, a glyph left out, a frame skipped after a GPU error or a layout that didn't settle showed "Something went wrong", sometimes in another window's banner. They are logged once as degraded:, in their own window's banner in debug builds only. zgx::issues::IssueKind, on_issue_kind and report_kind tell them apart; ScriptHost::on_issue and issues() give apps and zgx inspect errors the kind. An app's on_error still hears them.
  • Pictures keep their files, not their pixels (zgx, zgx-gpu, zgx-script): a script's src image is read for its size alone, decoded off the main thread when drawn, shrunk to the size it shows, and its pixels given back once uploaded (1.5 s on). A page of eight large photos: footprint 662 → 294 MB. A picture over 256 by 256 pixels shows a frame later than before; one up to that size (an icon) decodes as it is first drawn, in that frame, and decode = "sync" (HTML's decoding, ImageData::set_decoding) makes any picture wait rather than pop in. The image cache's budget counts files' bytes now; ImageData::pixels still gives all the pixels (decoded once and kept), and pixels_at, keeps_file, bytes, set_decoding, zgx::image::Decoding and zgx::image::release_decoded are new.
  • monospace is Menlo on macOS (zgx-gpu): every app's monospaced text now has a face of its own on macOS, as on Windows (Cascadia Mono or Consolas) and Linux. cosmic-text named Noto Sans Mono, which macOS lacks, so each word took the fixed-width face with most of its characters; Latin text already came out in Menlo. A word mixing Latin with characters Menlo lacks (Chinese, Japanese, Hebrew) now takes its Latin letters from Menlo and the rest from another face, where it could take all of them from one.
  • zgx_3d::POINT_LIGHTS is 8 (zgx-3d, #1123), the point lights a frame shades (the nearest the camera's target); it was 4. Its spelling is the same, but an array sized by it now holds eight, and a scene with five to eight point lights now shades them all. Migrate: size by the constant, not by 4.
  • zgx_script::Window and driver::Line keep 0.1.6's fields (zgx-script): code building them with a struct literal compiles as before. A window's under_pointer, visible and own state are read with ScriptHost::window_extras(id) (a WindowExtras, non_exhaustive with Default, beside window_size_limits), and whether a tree line's node shows with driver::tree_lines, whose TreeLine holds the Line and its hidden flag; tree and tree_text are as in 0.1.6.
  • TabsOptions keeps the fields 0.1.6 published (zgx-components): reorderable and on_close, as published zgx-script 0.1.6 builds it by literal. What tabs gained since (keep, group, on_move, on_tear_off) is in TabsMore, made from Default and its fields set, and passed with tabs_with(label, items, selected, options, more, panel). tabs is as it was.
  • A tab can stay home when torn off (zgx-components, zgx-script): on_tear_off returns whether it takes the tab. false keeps it in items, its preview sliding home, as an app's "All" tab needs; Luau's returning nothing still tears it off. TabsMore::on_tear_off's TearOffTab now returns a bool.
  • A terminal is a document named Terminal to assistive technology (zgx-terminal): its rows were children of an unnamed container that AT-SPI, UIA and AX drop, so they read as the window's own lines. They now sit in a document named Terminal (AT-SPI document frame, macOS AXDocument).
  • Screen readers hear a terminal's new output, not each keystroke's line (zgx-terminal): an engine-drawn terminal's rows are text labels (they were images), and new output is a live region of its own saying the lines output brought in or what a line gained; before, the whole terminal was the live region and a reader re-read the prompt's line with every character the shell echoed. Checked with Orca on Linux and the AX tree on macOS.
  • A test's clicks are counted as a person's (zgx-script): zgx test's and TestApp's presses come with the keys held, as a window's do, so on_press's clicks and a double click count in a test as they do in a window; separate app:click calls in a row still count as separate clicks (InputDispatcher::forget_clicks).
  • A test or devtools action says what is in its way (zgx-script): click, double_click, type, fill, hover and drag in zgx test, and zgx inspect's actions, fail on a target outside its scroll's clip naming the clip ("scroll it into view first"), and on one under another node naming that node and where, rather than acting on whatever was there. Input's InputDispatcher::pointer_target is public: what a press at a point lands on.
  • A field with nothing to undo hands ⌘Z on (zgx), and ⌘⇧Z or Ctrl+Y with nothing to redo, to the app's commands, as AppKit's responder chain does: a ui.command { key = "cmd+z" } reaches the app's own undo from inside a field without reserved = true. A field with a step still takes the key.
  • WindowOptions has new fields, max_size and visible (zgx-desktop): a WindowOptions written out field by field stops compiling. Migrate: end it with ..Default::default(), or set max_size: None and visible: true.
  • Wheels and drags in a zoomed box move it as far as the hand (zgx, zgx-script): a scroll view's offset, on_wheel's dx and dy, and anime.createDraggable's position took the window's points, so under zoom = 0.5 content moved half as far as the wheel or pointer did. They are in the box's own points now. A drag's grab_x, grab_y are from where the source shows. An app that scaled these for its own zoom now scales twice. docs/reference/events.md says which points each field is in.
  • ui.span reads the options its table holds (zgx-script): one walk over them, rather than a lookup for each of twenty names, makes a plain span's script cost about 40% less. A span's table is read as a plain table, as an element's is: options behind a metatable's __index are no longer seen.
  • Backspace follows the platform's text fields (zgx): it took a whole grapheme everywhere, so a mistyped tone mark in Thai or vowel sign in Devanagari took the syllable with it. In Hebrew, Arabic, Indic and Southeast Asian scripts it now takes one code point, as every browser and NSTextView do. An emoji, a flag, a keycap and a CRLF go whole. Where platforms differ it follows the native field: on macOS an accent, a dakuten or Hangul jamo goes with its letter, as in NSTextView and Safari; elsewhere one code point goes, as in Chromium. The caret and forward delete still move by grapheme.
  • ui.select, ui.combobox and ui.date_picker are the box they are given (zgx-components): id and sizes reached a wrapper the trigger sat in at its own width, or (combobox, date picker) the closed popup, so #id found nothing and w sized the panel. Now id finds the control, w and grow size it, and in a ui.column it fills across as an input does. w or the parent's items = "start" narrows one that used to hug its text. Rust's select, combobox and date_picker too.
  • A script's root fills its parent across (zgx-script), as a block does: return ui.column { … } was as wide as what it held. Its bg now reaches the edge, and items and justify work across the whole width. Height is unchanged: it takes what it holds, and h_full asks for the rest. A root with a w keeps it, and embedded in a Rust view it fills the box it is given. Scripts updating under such a root cost about 6% less: their rows are no longer measured twice.
  • A ui.list's rows fill its width (zgx): a row's root shrank to what it held, where a block fills the row. Its bg and borders now reach the list's edge, and what grow or justify spread goes across the whole row. A row with a width of its own (w) keeps it.
  • A scroll view or list under ui.show, ui.switch or ui.presence fills its parent (zgx): it stayed at its default 320 points (240 tall for a ui.scroll), where on its own it stretches, and what lay past that was clipped and took no click or drop. Check a view that looked right at 320: give it a w, or a max_w, to keep that width.
  • ui.each rows stretch as any child does (zgx-script): a row of each shrank to what it held, where the same node on its own fills its parent (columns' and rows' items defaults to "stretch"). A row's bg now reaches the edge, and what grow spreads goes across. In a ui.row, a child of each likewise takes the row's height, as a plain child does. A child with a w or h, or a parent with items, keeps what it said; one that relied on shrinking wants self = "start".
  • PaintExtras has a new field, outer_mask (zgx), for a fade inside a fade: a PaintExtras written out field by field stops compiling. Migrate: end the literal with ..Default::default(), or set outer_mask: None.
  • zgx::switches::ALL is [&Switch; 4] (zgx), with BAKED_LOOPS; it was [&Switch; 3], so code naming that length stops compiling. Migrate: iterate it, or take a slice (&zgx::switches::ALL[..]), and don't name its length.
  • local_x and local_y read through zooms and transforms (zgx-script, zgx), the node's own included, as CSS's offsetX: they were the window's point less the laid-out corner, so anything zoomed or moved by a transform read wrong. A script that corrected for its own zoom now corrects twice, and one that reads them on a transformed node gets the point in its untransformed box. ContextMenuEvent::local_x and local_y are the same.
  • A bare perspective on a node with none holds from the first frame (zgx-script): anime tweened it up from 0, past the eye. perspective = { from, to } still tweens.
  • Frames past a budget no longer fail (zgx-gpu): GpuRenderer::render returns Ok where it returned an error for layers, images, native surfaces, glyphs and shadows past their limits; it draws what it can, and GpuRenderer::take_issues says what it went without. A host that drew through render itself should hand those on.

Added

  • selection_radius (zgx, zgx-script): a selectable region's highlight corners, beside selection_color, over the $selection.radius token; a state or function follows.

  • glTF lights and cameras; spot lights, and lights that follow objects, in 3D scenes: a model's KHR_lights_punctual lights (suns, bulbs and spots, glTF's units as zgx-3d's) are added with it, each following its node, and Placed::lights() gives them; Placed::cameras(&world) gives its cameras where its nodes are now, for World::set_camera. World::set_light_parent(light, Some(id)) places any light in an object's frame, and World::set_spot(light, Some(Spot::new(direction, inner, outer))) shines a point light as a cone. A frame now shades with the eight point lights nearest the camera's target, where it took four. A world using none of these binds nothing new.

  • Widths from what an element holds (zgx, zgx-script): w, min_w and max_w take "min-content", "max-content", "fit-content" and "fit-content(320px)" (.w_calc("max-content".parse()?)), as CSS's: a badge as wide as its text in a column, with no on_resize.

  • A host can ask a capability of every plugin contribution (zgx-script): ScriptHost::require_contribution_capability(capability) makes adding into a slot (ui.contribute(name, node)) or before or after an element (by #id or a hook) take that capability, so an app can lock plugins out of its interface. A target or slot the host opens with expose_hook(target, None) ("slot:name" for a slot) stays open. Without it, contributions are open, as before.

  • display = "contents" (zgx, zgx-script): an element's children lay out in its place, as its parent's own (CSS display: contents), and ui.each(items, row, { display = "contents" }) makes its rows a grid's cells or a row's items rather than one box. Focus order and assistive technology keep the element where it is, with a role or label it has. In Rust, .display_contents() and Scene::set_display_contents.

  • Dotted borders, and dashed and dotted outlines (zgx, zgx-gpu, zgx-script): BorderStyle::DOTTED (a Dashed of length 0) draws round dots as wide as the border, as far apart, spread evenly round the box and its rounded corners; Luau border_style = "dotted". Styled::outline_style (and Scene::set_outline_style) draws an outline dashed or dotted, as CSS's outline-style; Luau outline_style = "dotted" and outline_dash = { length, gap }. A solid outline is the shader's ring as before; a broken one is rasterized once and kept. A canvas stroke's dash may now be 0 long (a dot, with round caps), as an HTML canvas's setLineDash takes.

  • on_double_click (zgx-script), as the DOM's dblclick, and app:double_click(target) in zgx test (TestApp::double_click).

  • Direct3D 12 compiles with DXC where the app ships it (zgx-gpu): with Microsoft's dxcompiler.dll beside the executable (14.3 MB; dxil.dll isn't needed), Windows shaders compile with DXC instead of FXC, and with FXC if that fails. A cold window's first text came sooner (437 ms against 776 on an RTX 4090), and DXC's output is kept in the shader cache as FXC's is. Nothing changes for an app that doesn't ship the DLLs (shipping).

  • A ui.textarea scrolls by line and says where it is (zgx, zgx-script): ui.editor.scroll_to_line(el, n, { align }) puts a line at the top, middle or bottom of the view, and on_top_line hears the first line in view: an outline can jump to a heading and follow the text (EditorHandle::scroll_to_line, View::on_top_line).

  • A field's undo and text position from a script (zgx, zgx-script): ui.editor.undo(el), redo, can_undo and can_redo, so an app can make one undo stack across panes, and ui.editor.offset_at(el, x, y), the byte under a point, so a drop goes where the pointer is (EditorHandle::undo, redo, offset_at).

  • A folder's files can be shown and handed on (zgx-script): folder:file(path), and folder:list(path, { files = true })'s entries, give a File that ui.image, ui.read_file and drag_export take as they do a dialog's, so a browser shows thumbnails and drags files out to Finder. A plugin with the grant can show the files it was given.

  • A folder can be kept past the run (zgx-script, zgx, zgx-desktop): ui.open_folder { remember = "library" } asks the host to keep the grant under that key, and ui.remembered_folder("library") settles with the handle on a later launch if the folder still resolves, or nil. folder:forget() drops it. The host keeps it where no script reads, in its storage's .folders: on macOS a security-scoped bookmark, which works sandboxed or not and follows the folder moved or renamed, elsewhere its path. Plugins keep none, and ScriptHost::refuse_remembered_folders() keeps none. Platform gains bookmark_folder, resolve_folder and release_folder, with defaults that keep a path.

  • Glass in 3D scenes (zgx-3d): World::set_transmission(id, Some(Transmission::new(1.).ior(1.5).volume(thickness, color, distance))) lets light through a mesh. What is behind it shows through, bent by its index of refraction, blurred by its roughness, tinted by its colour, and in a volume dimmed by how far the light goes. glTF models bring theirs: KHR_materials_transmission, KHR_materials_ior and KHR_materials_volume, their factors and their transmission and thickness textures (Map::Transmission, Map::Thickness). A world with glass draws its other meshes a second time a frame into a picture of what is behind; a world with none draws nothing more, binds nothing new, and draws its frames slightly faster than before (3d-textured −0.5%, 3d-mixed −0.8%).

  • Grid areas, named lines and dense flow (zgx, zgx-script): areas = { "head head", "side main" } names a grid's cells and area = "main" places an item in one (CSS grid-template-areas, grid-area). [name] in cols and rows names a line, grid_column and grid_row take CSS's "side / main" and "2 / span 3", and flow = "dense" fills holes. In Rust: grid_template_areas, grid_area, grid_column, grid_row, grid_flow.

  • Windows made hidden, shown fully drawn (zgx-desktop, zgx-script, zgx-run): WindowOptions { visible: false, .. }, ui.window { visible = false } (or a state) and zgx.json's "visible": false make a window hidden, its content laid out, its script running and its first frame drawn meanwhile; hidden, it draws nothing more. WindowHandle::set_visible(true), or ui.window.visible:set(true) for zgx-run's window, draws what changed since before it appears, so it shows whole at once, with no blank frame. On Wayland, where a window appears as it first draws, its first frame is drawn as it shows; on X11 a window keeps no picture while unmapped, so its theme's background (not black) shows for the few milliseconds between its mapping and its first frame.

  • Clicks land where an animation is going (zgx, zgx-script): hit = "target" hits an element, and what it holds, where its ui.tween, ui.spring, anime or layout animation is taking it, not where it shows: clicking fast on a stack that re-fans after each removal removes the photo under the pointer each time. Assistive technology reads it at its goal too. In Rust, Scene::set_hit_target gives any node a HitTarget; Scene::hit_bounds is where it takes hits. Also: a node removed with size math's content widths no longer leaves them behind.

  • Hyphenation (zgx, zgx-gpu, zgx-script): words break at their hyphenation points, a hyphen ending the line, as CSS's hyphens: auto, in the system's language, from typst's hypher (48 languages). In 0.1 it's a font feature, inherited as features are: FontFeatures::with_hyphens(true) in Rust, font_features = "hyphens" in Luau; hyphens = "auto" of its own waits for 0.2. It's behind a hyphens feature (zgx-desktop's), off by default, about 1.2 MB, read in place; without it, Luau's "hyphens" is an error where scripts are linted (a debug build, zgx lint). The text is unchanged: selection, carets and copying see the word whole. zgx-cosmic-text is 0.19.5.

  • Pixelated images (zgx, zgx-gpu, zgx-script): Styled::image_rendering(ImageRendering::Pixelated) (Scene::set_image_rendering), Luau image_rendering = "pixelated", as CSS's image-rendering: an image, or a background image, drawn larger or smaller takes each point's nearest pixel, its edges hard, for pixel art, a magnified screenshot or a QR code. Its draw samples with a nearest sampler of its own (wgpu a bind group, Metal pipelines, Direct3D 11 a sampler state, each made with the first): the shaders are as they were, and an image not pixelated draws exactly as before, in as many draws.

  • An app's main window reopens where it was left (zgx-run): "frame_autosave": true in zgx.json saves the window's frame under the app's app_id, so each app zgx-run runs keeps its own, and a string saves it under that name, as ui.window { frame_autosave } does for an app's other windows. zgx.json rejected the key.

  • TextEditor::move_visually_at (zgx) moves left or right as the text shows it from a caret place (TextPosition, with its affinity), stopping on each side where bidirectional runs meet, and returns the place it went to draw the caret there. move_visually, 0.1.6's form, keeps its signature and moves from the caret's byte.

  • ui.open_folder (zgx, zgx-script): a folder a person picks, as a handle only the dialog makes, which lists, reads and writes inside that folder and nowhere else: .., absolute paths and links out of it are refused, it works off the main thread, and a write replaces its file whole. A plugin needs the folders grant, and a Rust host can refuse it to every script (ScriptHost::refuse_folders, Capability::Folders, Platform::open_folder).

  • The primary selection through Platform (zgx, zgx-desktop): primary_text and set_primary_text read and set X11's and Wayland's primary selection (what a middle click pastes; none elsewhere). An engine-drawn terminal's selection becomes it as the drag ends, and a middle click there pastes it, as Linux terminals do.

  • Find's marks and an editor's decorations are rounded as a selection is (zgx): each match is one shape over the lines it runs on, rounded by the new $mark.radius token, which follows $selection.radius unless a theme sets it. Scene::set_text_mark_shapes sets marks so; set_text_marks keeps its look. An editor's decorations are marks on one node of their own, not a rectangle node each.

  • Lint list-row-get (zgx-script): state:get() straight in a positional ui.list's row builder, which is read once per index and goes stale as the list changes; data with a key makes each row follow its item.

  • Any element can be a slider to screen readers (zgx, zgx-desktop, zgx-script): Luau's role = "slider" on a column, row, div or overlay, with value, min, max, step and value_text (all followed where they can change), on_change(value), and keyboard = true. In Rust: View::role(Role::Slider), numeric_when and value_when, plus the new View::adjustable(step, on_change) and adjustable_keys. VoiceOver, Narrator and Orca read the value, its range, its step and its value text ("High", not "3"), and increment, decrement and set it through on_change. With keyboard, the arrows, Page Up and Down, Home and End move it as ui.slider's do, and it becomes focusable. ui.slider now tells screen readers its step and takes value_text too. On Linux, the value text is AT-SPI 2.46's Value.Text in builds from this repository, which patch in accesskit_unix. A build from crates.io, with upstream accesskit_unix, gives Orca the number, range and step without the text.

  • Autocorrect and smart punctuation, opt-in per field (zgx, zgx-desktop, zgx-script): View::autocorrect (Luau autocorrect = true) corrects a misspelled word as it ends and expands the person's text replacements ("omw" to "On my way!"); View::smart_punctuation (smart_punctuation = true) makes straight quotes curly and -- a dash as they are typed. Both go through the system's own services (macOS's NSSpellChecker, in the forms the person chose), only where the person has them on in System Settings, and never in a password field. Each substitution is an undo step of its own: undo puts back what was typed, and it stays. Off by default; other platforms substitute nothing yet (Platform::substitutions, Platform::correction).

  • Tabs move between strips (zgx-components, zgx-script): ui.tabs { group = "panes", reorderable = true }, a tab dragged over another strip or panel of the group goes there, as in an editor's split panes; on_move hears it (TabsMore::group, on_move, through tabs_with).

  • Tabs tear off into windows (zgx-components, zgx-script): with TabsMore::on_tear_off (Luau ui.tabs { on_tear_off }), a reorderable tab dragged off its strip is carried as a drag, its chip under the pointer. Dropped on a strip of its group in any of the app's windows, it goes there and on_move is told. Dropped back on its own strip, it stays. Released outside every window, it leaves items and on_tear_off is told its id and where it was grabbed, to open it in a window of its own (ui.windows, under_pointer).

  • An app answers a terminal program's request to read the clipboard (zgx, zgx-terminal, zgx-desktop, zgx-script): Terminal::on_clipboard_read (Luau: ui.term's on_clipboard_read) gets each OSC 52 read as a ClipboardRead to allow() or deny(), at once or after a prompt the app shows; a request let go is denied. Without one, Ghostty still asks with its own dialog and the engine-drawn terminal denies, now with an empty answer the program can read rather than none.

  • Terminals on Windows and Linux (zgx-desktop's terminal feature, on in zgx-run): zgx::terminal::terminal and Luau's ui.terminal draw a session with zgx itself on every platform: a pseudoterminal (openpty, ConPTY) and its screen, in the window's own text, each row drawn again only when it changes. Colours to true colour, wide and emoji cells, cursor shapes, the alternate screen, scrollback, selection and copy, bracketed paste, mouse reporting, OSC 8 links, input methods at the cursor, and the session's title, directory, progress, bells, exit and foreground process (an app's resolver included) as with Ghostty. An idle terminal does no work. On macOS, ghostty still draws them when it is on. What it can't do yet (images) is in docs/native-surfaces.md.

  • The kitty keyboard protocol in engine-drawn terminals (zgx-terminal): a program that asks (CSI > flags u: Neovim, Claude Code and other agents) gets its keys as the protocol encodes them: Ctrl+C as CSI 99;5u rather than ^C, Escape as CSI 27u, repeats and releases, shifted and base keys, every key as an escape with its text, and its flags answer CSI ? u.

  • Terminal sessions on every platform (zgx-terminal, new): a shell or any command on a pseudoterminal (openpty on Linux and macOS, ConPTY on Windows) and the screen it draws, kept by alacritty_terminal: colours and true colour, wide characters, scrollback, the alternate screen, synchronized output. Session does its I/O on a thread of its own that sleeps until the program or the app writes, and wakes the app once until it reads, so a flood of output costs one update per read and an idle shell nothing. Titles, the working directory (OSC 7), bells, progress (OSC 9;4), finished commands (OSC 133), notifications (OSC 9/777), clipboard requests (OSC 52), the foreground process and exit codes come back as events. The engine-drawn terminal view builds on it.

  • app:copy_file(from, name) in zgx test (zgx-script): a fixture from the app's directory, an image or a folder of them, copied into the test's own files for a dialog to answer with; write_file takes text only.

  • A test acts in the app's other windows (zgx-script): app:window(id) in zgx test is a window the app declares (ui.window, or one of ui.windows) with an app's methods, nil while it is closed. It shares the app's state, tasks and frames as a desktop app's windows do, and close() closes it as a person does. In Rust, TestApp::window(id) mounts one as a TestApp of its own.

  • Balanced text: wrap = "balance", Styled::text_balance (zgx, zgx-script): wrapped text breaks at the narrowest width that keeps as many lines, so a heading's last line isn't left short, as CSS's text-wrap: balance does, for up to six lines. Inherited, as CSS's is; boxes and line counts are as they were. Scene::set_text_balance sets it, and Scene::text_wrap is what renderers read.

  • Han characters take the app's language's fonts (zgx, zgx-gpu, zgx-desktop, zgx-script): a script with ui.i18n sets the windows' text language to its locale, as CSS's lang on a document does, so a Japanese locale's kanji draw in a Japanese face and zh-TW's in a traditional Chinese one, whatever the system's language. Rust apps call WindowFactory::set_text_language; Platform::set_text_language carries it, and FontSystem::set_language in the fork applies it. A Chinese, Japanese or Korean language set takes precedence over a line's own kana or hangul. A system locale such as ja-JP now gives Japanese faces too (the fallback lists named only ja).

  • Text shadows (zgx, zgx-script): Styled::text_shadow(x, y, blur, color) and text_shadows, Luau text_shadow = { x, y, blur, color } or a list, as CSS's text-shadow: the glyphs again under them, moved and tinted, inherited by the text inside. Scene::set_text_shadows for scenes built directly. blur blurs it (a Gaussian's sigma in points): each glyph's coverage is blurred once and kept in the glyph atlas, so a blurred shadow costs a frame what a sharp one does, on every backend. Shadows paint outside the text's box, as CSS's do (a text itself stays clipped to its box).

  • A window an item, from Luau (zgx-script, zgx-run): ui.windows(list, build, { key, on_close }) opens a window as an item appears in a list and closes it as the item goes, as ui.each does rows: a detail window per photo, a tab torn off into a window. A person closing one calls on_close(item). under_pointer opens a window under the grab, on ui.window too.

  • Screen readers read web pages on Linux (zgx-desktop's webkitgtk): a page's accessible tree, which WebKit serves from its own process, is the window's too, under the page's box (an internal frame), with the box for its parent, so Orca follows focus into the page and reads it: its focused field, its headings by its browse mode's heading keys. GTK's own window for the page says nothing to a reader, and GTK here names WebKitGTK as its toolkit, so Orca keeps its web script (and its browse mode) for the page. NodeHandle::touch_semantics (and Semantics::touch) has assistive technology read a node anew when what a host adds to it changes; a gpu_view with an empty label is none of assistive technology's.

  • Tab into a web page on Linux focuses its first field (zgx-desktop's webkitgtk): Tab or Shift+Tab reaching a page's box focuses the page's first or last focusable element, as tabbing into a browser's frame does, and a screen reader names it ("Probe field entry.") rather than reading what it holds.

  • Web views on Linux (zgx-desktop's webkitgtk feature, which zgx-run turns on): zgx::web_view and ui.webview show WebKitGTK 4.1 pages on X11 and Wayland, drawn offscreen and shown as images, so they clip, round, fade and take zgx content and glass over them as any node does. Pointer, keys (reserved shortcuts first, keys the page leaves alone falling through to the app's), input methods, <select> popups (as zgx menus), the clipboard (bridged through zgx's on Wayland), navigation, scripts, messages, app schemes, profiles and the inspector work as on macOS. WebKitGTK is opened at run time (libwebkit2gtk-4.1-0): building needs none of it, and without it pages stay placeholders. Two CPU copies a frame, and no drags out of a page yet: see docs/linux.md.

  • A window's largest size (zgx-desktop, zgx-script, zgx-run): WindowOptions::max_size and WindowHandle::set_max_inner_size, beside min_size; zgx.json's max_width and max_height; and ui.window { min_width, min_height, max_width, max_height }. The same minimum and maximum make a window of fixed size that stays resizable to the system, so window managers such as Raycast can move it on macOS, which they refuse for one that isn't resizable.

  • ui.window_rect(el) (zgx-script): where an element shows in the window, through every zoom and transform around it, as { x, y, width, height } in window points (CSS's getBoundingClientRect). A ref's x, y, width and height stay as laid out.

  • A window reads its own state (zgx-script, zgx-run): ui.windows' build(item, win), and ui.window content given as function(win), get win.active, win.shown and win.size, that window's, where ui.window.active is the main window's: a command can act on the window in front.

  • Size math (zgx, zgx-script): w, h and their limits take calc(100% - 24px), min(…), max(…) and clamp(…) (.w_calc("…".parse()?) in Rust), worked out from the containing block as CSS's are, with no on_resize writing state.

  • A ui.list row taller than height is a layout warning (zgx): it ran over the next row silently.

  • Spans follow state, and take any font (zgx-script): a span's color, bg, text_size, weight, bold, italic, underline, strike and font take a state or a function, as its text does, so a run restyles without rebuilding its paragraph's node or losing a selection in it, and font takes what ui.text's does (text).

  • Sticky elements in scroll views (zgx, zgx-script): .sticky_top(n) and sticky_top = n hold an element n below the top of the ui.scroll around it as it scrolls past, inside its parent, as CSS's position: sticky with top: section headers, with no script running as it scrolls. Vertical scroll views only.

  • Vertex colours in 3D scenes: Geometry::with_colors(colors) gives each vertex a colour, multiplying its material's and its base colour map's across each triangle. glTF models bring theirs (COLOR_0: red, green and blue, with alpha or not, in floats or normalized integers), and a BLEND material whose alpha is only in its vertices draws translucent. A geometry without them binds nothing new.

  • Where a map sits on a 3D mesh: World::set_map_placement(id, Map::BaseColour, Some(MapPlacement::new().scaled(4., 4.).wrap(Wrap::Mirror, Wrap::Repeat))) moves, scales and turns each of a mesh's maps on its own, says how it repeats, and with .uv_set(1) reads the coordinates Geometry::with_second_uvs gave it. glTF models bring theirs (KHR_texture_transform, samplers' wrapS and wrapT, texCoord and TEXCOORD_1). A mesh's maps share one sampler, its first map's wrap. A mesh using none binds nothing new; a wrap alone only takes another sampler.

  • OpenType features in Luau (zgx-script): font_features = "ss01 cv02=3 liga=0", as CSS's font-feature-settings, on any text or what holds it, followed from a state or function (properties).

  • z (zgx, zgx-script): .z(n) and z = n paint and hit a node over its siblings with a lower z, for a raised card or a badge. Among siblings only, unlike CSS's z-index: there are no stacking contexts. Layout, Tab order and accessibility keep document order, as in CSS (stacking).

  • Double-sided and cut-out meshes in 3D scenes: World::set_double_sided(id, true) draws a mesh's back faces too, and World::set_alpha_cutoff(id, Some(0.5)) cuts it out by its base colour texture's alpha, in its shadow as well (leaves, hair, fences). glTF models bring theirs (doubleSided, alphaMode: MASK and alphaCutoff). A BLEND material whose alpha is only in its texture is now translucent, where it drew solid. A mesh using neither binds nothing new.

  • zgx test reads more (zgx-script): app:text gives a field's value, app:selection its selection, app:tree takes a target, and ~"part" targets what a label or text holds, anywhere in it (in zgx inspect too). ui.combobox's items may be a plain list.

  • ui.tabs { keep = true } (zgx-components, zgx-script): a tab's panel stays mounted once chosen, hidden, until its tab closes, so an editor keeps its undo, caret and scroll across a tab switch (TabsMore::keep, through tabs_with).

  • Grid tracks of any size (zgx, zgx-script): cols and rows take a list as CSS's grid-template-columns writes it, besides a number of equal tracks: cols = "220 1fr auto", minmax(), fit-content(), repeat(), and cols = "repeat(auto-fill, minmax(240, 1fr))", which reflows cards with the window and runs no script. In Rust, .grid_template_columns(tracks) and .grid_template_rows(tracks) with zgx::grid_tracks::GridTracks. What CSS rejects is an error saying why (grid tracks).

  • Morph targets in 3D scenes: Geometry::with_morph_targets(vec![MorphTarget::new(positions).with_normals(normals)]) gives a mesh shapes to blend toward, and World::set_morph_weights(id, &weights) (or set_morph_weight, one target) how much of each, on the GPU, before any skin; its shadow and picking follow. glTF models bring their targets (positions and normals), their mesh's or node's weights, and clips moving the weights, so ui.model { animation = … } plays them. A target in a sparse accessor isn't read yet: that mesh shows unmorphed. A scene without targets, or with every weight 0, binds nothing new.

  • glTF sparse accessors: any of a model's accessors may be sparse: its positions, normals, texture coordinates, skins, indices and animation keys, over a base or over zeros. Blender exports its morph targets this way, so those models morph now.

  • Morph targets in 3D scenes: Geometry::with_morph_targets(vec![MorphTarget::new(positions).with_normals(normals)]) gives a mesh shapes to blend toward, and World::set_morph_weights(id, &weights) (or set_morph_weight, one target) how much of each, on the GPU, before any skin; its shadow and picking follow. glTF models bring their targets (positions and normals), their mesh's or node's weights, and clips moving the weights, so ui.model { animation = … } plays them. A scene without targets, or with every weight 0, binds nothing new.

  • Editors hear a paste before it goes in (zgx, zgx-script): ui.textarea { on_paste = function(e) … end } (View::on_paste), as HTML's paste event, from a key, the Edit menu, the context menu or a middle click. e.text is the clipboard's, nil for an image, e.files the files copied in Finder, Explorer or a file manager (Platform::clipboard_files), readable as ui.open_files's are, and returning true takes the paste: a composer can make a pasted picture, a file or a long text an attachment. Hosts paste through Ui::paste_into (controls).

  • zgx new --template plugins (zgx-script): tasks made to be extended. Its zgx.json exposes shared state, an action the script defines with ui.actions, and a list to filter. plugins/focus is allowed them, adds beside the app's hook, filters the list and calls the action. Its test mounts the app with its plugin, as zgx run does.

  • Plugins in a Luau app, from zgx.json (zgx-script, zgx-run): expose is what the app offers plugins (shared state read only or written, actions, targets to replace or filter), and each plugin's allow is what it's granted (shared:<key>, action:<name>, override:<target>, fetch and the rest). A grant beyond what's exposed is an error naming the plugin and the grant. zgx run, zgx test and zgx audit load them alike (zgx_script::app_config). ui.actions { name = function(arg) … end } defines the app's own actions, called as a Rust host's are (ui.invoke, ui.action). A plugin's ui.shared default now gives way to the app's, since plugins load first (plugins).

  • 3D camera controls as a model viewer's: zgx_3d::OrbitControls answers a view's input: drag to turn, right- or middle- or Shift-drag (and Shift-scroll) to pan, scroll or pinch to zoom, and, focused, arrow keys to turn (pan with Shift), + and - to zoom and Home to come back; a flick coasts to a stop (coast, a frame at a time while it coasts), not with reduced motion. Orbit::pan moves its target. ui.scene3d { orbit = true } uses it (orbit = { pan = false } turns panning off), focusable, in Rust with no script per frame; with reduced motion on, flicks stop where let go and auto_rotate holds still. A camera.target from a state now moves the orbit's target only as it changes, so a pan stays.

  • 3D anti-aliasing you can turn off, and smoother highlights: World::set_samples(1 | 4) (in Luau ui.scene3d { antialias = false }): 4 samples a pixel by default as before, 1 for hard edges at a quarter of the colour and depth memory. Multisampled scenes now also widen a surface's roughness where its normal turns faster than the pixels show (geometric specular anti-aliasing, Tokuyoshi and Kaplanyan), so highlights on fine curves blur instead of flickering: about 1% more GPU work (scene3d demo 42.7–43.1 → 42.8–43.3 Mcycles/s), none at one sample.

  • Editors' highlight colours follow a theme switch, and a highlighter's state is any value (zgx-script): a highlight span's "$token" colour is resolved again when the theme's tokens change (ThemeScope::revision, now public), at no cost while they don't. What a line leaves the next can be any Luau value (a string, a boolean, a table), not only a number: the same string or number is the same state, a table the same one only as itself (controls).

  • read_only on inputs and text areas (zgx-script): ui.textarea { read_only = locked } (a boolean, a state or a function, as View::read_only_when) keeps the field selectable and focusable and refuses the person's edits; value still sets it (controls).

  • ui.window.size (zgx-script): the window's size in points, read-only and followed (ScriptHost::window_size, which zgx run calls), for decisions layout can't make, such as a sidebar collapsing to icons. A new lint, window-size-layout, reports an element's size computed from it, which layout does without the script (native).

  • ui.each takes a plain table, and dates and times can be controlled (zgx-script): a list that never changes needs no state; ui.date_picker, ui.calendar and ui.time_field take value = function with on_change, as ui.select and ui.checkbox do.

  • Text on a canvas (zgx, zgx-script): c:text(text, x, y, { size, color, weight, align, baseline, tabular, font }) and c:measure_text(text, opts), Canvas::text and zgx::canvas::measure_text in Rust. A chart's labels are shaped and drawn as any text is, sharp at any zoom and with fallback fonts, over the canvas's shapes. A canvas without text pays nothing for it. Assistive technology reads the canvas's label, not its text.

  • Tone mapping and exposure in 3D scenes: World::set_tone_mapping(ToneMapping::Neutral | Aces | Linear) and World::set_exposure(stops). Khronos's PBR Neutral stays the default (colours read true, only highlights roll off); Aces is the filmic curve (Stephen Hill's fit, exposed by 1/0.6 as three.js does, so mid grey stays about mid); Linear clamps. In Luau, ui.scene3d { tone_mapping = "aces", exposure = 1 } (exposure reactive). Output stays sRGB-correct either way (linear 0.18 shows as 118 of 255).

  • app:hover(target) in zgx test, TestApp::hover in Rust; a ui.progress takes a number or a function (zgx-script): a tooltip can be tested, and a bar in a list row needs no state. zgx test no longer warns that ui.persist has no storage, which it never has.

  • zgx new <name> (zgx-script) writes a Luau app that runs at once (zgx run), from one of four templates: basic (tasks), router (notes with routes and a modal route), list (a long list paged as it scrolls, searched as you type, reorderable favourites) and form (a profile form). Each has a component, a theme of the app's own tokens (read as ui.tokens.app.*), a test, zgx.json, .luaurc, its editor types, a README and a GitHub Actions workflow running zgx check, zgx lint, zgx audit and zgx test, all four clean. --i18n writes its text as ui.t messages with locales/en.json (getting started).

  • Image-based light in 3D scenes: World::set_environment(Some(Environment::studio())) lights every surface from all around, its reflections sharp in polished metal and blurred in rough (split-sum: a cube prefiltered at five roughnesses, Karis's fit for its second factor, nine spherical harmonics for its diffuse light). Environment::decode_hdr reads a Radiance .hdr image (equirectangular), from_equirect and from_cube take linear RGB; intensity and rotated brighten and turn one. In Luau, ui.scene3d { environment = "studio" | "none" | "sky.hdr" | { src, intensity, rotation } }, and a scene showing a ui.model has the studio unless it says otherwise. Prefiltering takes 11–16 ms off the main thread (the studio once an app); its cube is 0.5 MB, written in place on Apple GPUs (zgx_gpu::viewport::cube_with_levels): no more driver blocks (Box 20, DamagedHelmet 23 with or without). A scene without one binds nothing new.

  • zgx run <app> (zgx-script) opens a Luau app in a window as zgx-run does, by the zgx-run beside zgx or on PATH (saying how to install it when neither is there), so one command runs, checks, lints, audits and tests an app. zgx audit finds it the same way.

  • Tests in Luau (zgx-script): zgx test runs an app's *.test.luau files, each test against the app mounted headless. A file gets three globals: test(name, body), mount(), and expect(v) with to_be, to_equal, to_contain, to_be_truthy, to_be_nil and their never forms. The app is driven by devtools' targets (#id, "label", role:button, #list row 3): click, type, fill, key, scroll, command, text, has, count, wait, state and set_state. A failure names its line, and zgx check knows the globals' types in test files alone. TestApp::try_new mounts or answers the script's error (testing an app).

  • Skinned meshes in 3D scenes: Geometry::with_skin(joints, weights) gives a mesh's vertices up to four joints each, and World::set_skin(id, Some(skin)) binds an object showing it to a Skin::new(joints, inverse_binds) (objects as joints, up to MAX_JOINTS, 256): the GPU places each vertex by its joints' matrices, so a clip moving the joints bends the mesh. glTF models bring their skins (JOINTS_0, WEIGHTS_0); its shadow and picking follow the pose. A scene without skins binds nothing new and costs what it did (the scene3d demo level, 23 driver blocks); CesiumMan walking with its texture: 25. Morph targets are not read yet.

  • zgx test drags (zgx-script): app:drag(from, to) drags one target onto another, as TestApp::drag does in Rust.

  • glTF animations: Model::clips (and clip(name)) reads a model's animations: channels moving its nodes' translation, rotation and scale, by STEP, LINEAR (rotations along the shorter arc) or CUBICSPLINE keys. World::place_model adds a model as add_model does and keeps its nodes' objects; Placed::pose(world, clip, seconds) poses a clip at any time. In Luau, ui.model { animation = "Walk" } (or its place, from 1) plays one round and round, posed in Rust a frame at a time. The model example plays a file's first clip.

  • A trackpad's swipe between pages goes back and forward (macOS): two fingers across (or three, as the system's Trackpad setting has it), as Safari does, over a view with on_navigate (zgx-script) or View::on_navigate (Rust), which hears "back" or "forward". A two-finger swipe navigates only where it starts where nothing under the fingers scrolls that way, so a carousel mid-content still scrolls; AppKit tracks it from there. With nothing that navigates under it, it scrolls and stretches as before (events).

  • Live connections (zgx-script): ui.socket(url, { json, reconnect, on_message, on_open, on_close, max_buffered }), as React's useWebSocket, keeps a connection open through the host's ScriptHost::socket_connector. It has status ("connecting", "open", "reconnecting", "closed"), attempt, retry_in and buffered as states, error as a UiError, and send(v) (text, or a table as JSON), send_bytes(s), close() and reconnect(). What is sent before it opens waits and goes in order. It opens again after a growing wait when its connection ends, and again at once when a state its URL function reads changes. ui.sleep(ms) is a promise to await in a task (state).

  • Files dropped from outside the window, and uploads (zgx-script, zgx-run): on_file_drop = function(files, e) and on_file_hover = function(over) hear files dragged in from Finder, Explorer or a file manager (react-dropzone's onDrop and isDragActive). A File now has size and type (its media type) as the web's does. ui.fetch(url, { file = f }) sends a file as the body, multipart = { … } sends a form's text and files as multipart/form-data, both read off the window's thread, and on_progress(sent, total) hears the body go out. zgx-run's fetcher tells it as it writes, and a host's streaming fetcher does with Body::sent (state, events).

  • Suggestions at the caret (zgx, zgx-script): ui.popover { at_caret = true, anchor = ui.textarea { … } } (View::at_caret) places a popover at the caret of the field in its anchor, as a mention's or a slash command's suggestions are. It follows the caret as text is typed, a line wraps, the field scrolls and an input method composes. It takes no focus, so the field's keys move through the suggestions, and active_descendant = id (View::active_descendant, HTML's aria-activedescendant) tells assistive technology the one it is on (overlays).

  • Scripts read whether their window is active and shown, post system notifications and badge the app's icon (zgx, zgx-script, zgx-desktop): ui.window.active and ui.window.shown (Ui::observe_window_active, Ui::observe_shown, published by ScriptHost::window_state), ui.notify { title, body, tag } (Platform::notify: macOS's Notification Center for a bundled app, a Windows toast for the app's identity, a Linux desktop's notification server), and ui.badge(n) (Platform::set_badge: the Dock's, a Linux dock's). A UiError gains the kinds "unsupported" and "denied" (native).

  • A component's id says when it replaces one inside (zgx-script): Panel { id = 5 } names the component's root, so an id set on that root goes unseen. A warning as it mounts names both ids and where, and zgx lint's component-id finds it within a file.

  • A popover can anchor to an editor's caret, and an editor can name its active descendant (zgx, zgx-script): ui.popover { at_caret = true, anchor = ui.textarea { … } } (View::at_caret) places a popover at the caret of the field in its anchor, as a mention's or a slash command's suggestions are. It follows the caret as text is typed, a line wraps, the field scrolls and an input method composes. It takes no focus, so the field's keys move through the suggestions, and active_descendant = id (View::active_descendant, HTML's aria-activedescendant) tells assistive technology the one it is on (overlays).

  • Lists report reaching their start and resting at their end, and keep their place when rows are added above (zgx, zgx-script): ui.list { on_start = fn, start_distance = 200 } (View::on_start) is called as the list's start comes in reach, as on_end is at its end, and at_end = state (View::on_at_end) follows whether it rests at its end. A list with on_start given rows above the ones in view (measured_rows, or ui.list with measured and key) finds the row it showed by its key and keeps it where it was, rather than letting the new rows push it down; other lists track nothing for it (scrolling).

  • The channels example: a team's chat in Luau against a server in memory, built on this release's primitives. It has a WebSocket that reconnects on its own with a banner while it does, messages shown at once and confirmed or refused (and sent again), unread counts and presence, a list that stays at its end and loads earlier pages at its start without jumping, mentions in a popover at the caret, an emoji picker, files dropped or attached and uploaded with their progress, and a system notification and the icon's badge for what arrives in the background. Run it with cargo run --release -p zgx-script --example channels.

  • A notification's click reaches the script, and Windows badges the taskbar button (zgx, zgx-script, zgx-desktop): ui.notify { on_click = fn } (Platform::next_notification_click) runs when the person clicks the notification, the app's window brought forward first: through macOS's notification center delegate, a Windows toast's Activated, a Linux server's ActionInvoked. A notification without a tag gets one of its own. On Windows ui.badge(n) is an overlay on the taskbar button, the count drawn and described to screen readers (native).

Performance

  • Scripts that update and scroll run faster than in 0.1.6 (exact instruction counts at the release on Linux arm64): updating a script's state costs 6.4% less and the lab's scroll 4.7% less; every other core benchmark is faster by 0.01% to 0.48% (heavy scrolling −0.48%, micro-state −0.34%, widgets −0.25%, animation −0.20%, mount −0.15%), or flat (script layout and list-state, +0.01%).
  • Textured 3D scenes draw in 63% fewer instructions a frame (8.81 → 3.25 M; the whole benchmark −56%); loading one costs about 5% more, for its larger shaders.
  • The example apps' interactions cost 0.06% to 0.40% more (app-sketch +0.40%, app-chat +0.29%, app-code-search +0.15%, app-mail +0.11%, the dashboard +0.06 to +0.09%, app-code +0.08%), zgx's own share 28 to 97 K instructions an interaction, the rest Luau (its garbage collector's pacing) and libc. Their causes are named, for 0.1.8: z ordering's bookkeeping (#1070), even in apps that set no z; percentage bases (#1116) in mail and chat; and the code editor's highlight conversion (#1020).
  • 3D frames set each pipeline, binding and buffer once a run of meshes needs it (zgx-3d): every run set them all again, the same or not. A frame of 2,000 varied meshes costs 6% fewer instructions.
  • 3D frames allocate almost nothing of their own (zgx-3d): every skinned or morphing mesh's pose went into a new list each frame, and a frame's working lists grew from empty. Poses now share one list apiece and the lists are kept between frames, so a frame of 2,000 skinned, morphing and textured meshes makes 180 allocations where it made 1,511, the rest wgpu's. Frames cost 1–4% fewer instructions and no longer change cost when other code shifts the heap. World::set_morph_weights copies into the list a mesh has.
  • 3D pipelines cost less to make (zgx-3d): a mesh variant's shader is written in one pass, copying only the lines it keeps, instead of being copied three times (prefixes, anti-aliasing, comments). Setup of the 3d-textured cell falls by 0.29 M instructions and of 3d-mixed by 1.18 M.
  • A canvas's filled areas draw on the GPU on Windows when the app ships DXC (zgx-gpu): with dxcompiler.dll beside the executable, an area chart draws as one quad again, where with FXC alone, which can't compile its shader, it rasterizes every redraw.
  • A field reads its code options with less work (zgx-script): highlight, decorations, underlines, tab, on_caret, on_top_line and find are read straight from its table, rather than by a protected lookup each, which every ui.input and ui.textarea paid.
  • A JPEG drawn small never decodes at full size (zgx, zgx-gpu): it decodes at 1/2, 1/4 or 1/8 of its size, the smallest that covers the size drawn, with the DCT scaled (zgx's fork of zune-jpeg, published as zgx-zune-jpeg; ImageData::kept_scaled and zgx::image::DecodeScaled are new). A kept image's decode no longer copies its pixels to premultiply them. A page of eight 4000 by 3000 photos as 300 by 420 cards: each decode's peak 91.6 → 18.6 MiB and time 47 → 22 ms; the process's peak about 490 → 330 MB. JPEGs decode through the fork directly, not image, which no longer carries a JPEG decoder of its own; their pixels are unchanged at full size.
  • Left-to-right text skips the bidi analysis (zgx-gpu): a line with characters beyond ASCII (accents, —, …, ×, emoji) but nothing right to left, no bidi control and no paragraph separator is laid out as one left-to-right run, as ASCII already was, without unicode-bidi's analysis. One look at its bytes decides; a test checks every code point the analysis treats otherwise is caught. The gate's lab-scroll (such text, scrolled) runs 4.4% fewer instructions.
  • New monospaced text no longer searches every installed font (zgx-gpu, zgx-cosmic-text): each new word of monospaced text (a terminal's every line, a log, a code view's edits) weighed every fixed-width face on the system before shaping. Its family's face is now kept, as other families' are, and the search runs only for a character the face lacks. Shaping a terminal's 24 new lines takes 32 µs instead of 135 µs, and an engine-drawn terminal printing 20,000 lines a second spends a quarter less CPU on macOS. A text's fallback families are looked up once rather than whenever it is laid out anew.
  • A scrolling terminal draws only its new lines (zgx-terminal): when output scrolled the screen, every row of an engine-drawn terminal was worked out and drawn again. The rows still on screen now move up with it, without layout, and only the new lines draw, so ordinary output (a line a frame) costs about a third less on the UI thread and 15% less in all, and a flood of output costs the same. Rows stay in reading order for screen readers.

Fixed

  • A canvas stroke no longer crashes a Windows app (zgx-gpu): Direct3D 12 compiling the canvas shader overflowed the stack inside FXC, Windows' shader compiler, so an app's first chart line, sparkline or stroke crashed it on a machine that hadn't cached the shader yet. Filled areas, whose shader FXC can't compile, now rasterize on Windows; strokes still draw on the GPU.

  • The arrows reach every place in mixed-direction text (zgx): where a right-to-left run meets a number or another run, a boundary has a place on each side, and Left and Right now stop at both, so the caret can sit after a number ending a Hebrew or Arabic run (to type more digits), not only after the run. At a line's visual edge the arrows no longer bounce back when its last run goes the other way ((אבג) [123] xyz); they stay, or go on to the next line.

  • A hot-reloading host's type check no longer piles up (zgx-script). In a debug build, every host with watch ran luau-lsp over the whole app after each reload on a thread of its own, and never stopped the previous run. With several debug apps open and agents saving files, hundreds of luau-lsp processes ran at once (531 on one Mac, which ran out of memory). Now a machine runs one check at a time, however many hosts and debug processes it has. A process's checks take turns on one thread, and processes take turns on an advisory lock file in the temporary directory, held only while luau-lsp runs. Each check starts once its host's saves have stopped for 300 ms. A newer reload replaces the host's check, killing its luau-lsp if it is running, and a dropped host kills its own. When nothing is asked for, the checker's thread waits, doing nothing.

  • A dialog asked for as a script loads opens, or says why not (zgx-script): ui.open_files, ui.save_file, ui.open_folder and the clipboard's images, called from a task at a script's top level, failed silently. They looked for the window's platform at once, before the view had mounted, and the load's success then cleared the error. They now look for it as their promise's work first runs, when the window is there, and an error reported while a script loads (a refused dialog, a task's failure) stays shown.

  • Colour emoji keep their colours (zgx-gpu): a colour glyph (an emoji) was multiplied by its text's colour, so grey text dimmed its emoji, black text drew silhouettes and red text tinted them red. Colour glyphs now draw in their own colours with the text's alpha (opacity and fades still apply), whatever the text's colour or selected-text colour, and their shadows are their shape in the shadow's colour. The software renderer already drew them so.

  • An emoji asking for emoji presentation draws in color (zgx-gpu): a cluster with U+FE0F, or a keycap's U+20E3, now comes from the color emoji font even where the text font has its characters. On Windows, Segoe UI has 1 and the keycap mark, so 1️⃣ drew as a black outline. Text-default symbols without U+FE0F stay in the text font.

  • What leaves takes no clicks (zgx-script): a ui.each row removed from its list, and what a ui.presence lets go of, play their exit where they were but the pointer passes through them to what's under, so a fast second click acts on what's still there, never on data already gone. A focused row leaving gives focus to the next row (else the one before, else the nearest focusable around it), Enter and Space never activate it, and assistive technology no longer offers it.

  • Escape gives focus back as browsers and native toolkits do (zgx). A popup closing returns focus to what had it before it opened. If that's gone, it returns to the popup's trigger, but only if the popup opened from the keyboard. Otherwise nothing is focused. Before, a popup opened with nothing focused gave focus to the window's first focusable control (Zeron's "New chat"), so the next Enter pressed it. Escape no longer turns focus rings on either, as :focus-visible has it: a menu opened by the mouse and closed with Escape gives focus back without a ring, and one moved through with the arrows keeps it. Tab, the arrows, Home/End, Page Up/Down and typing still turn rings on, and shortcuts with Cmd, Ctrl or Alt don't. A context click on a focusable view focuses it before its menu opens, as a press does in a browser, so the menu gives focus back to it.

  • A broken Ghostty checkout in zgx-ghostty-sys's cache is fetched again, not a failed build: one left without its files (as a cache keeping only part of a directory leaves it) is deleted and fetched anew, with a cargo:warning saying so. Only a checkout the build script made, marked by its .zgx-ghostty-checkout file, is ever deleted; an unmarked one stops the build with what to do.

  • A Japanese line's kanji draw in a Japanese font (zgx-gpu): Han characters took the fallback font of the system's language, so on an English system a Japanese line's kanji came from a different font than its kana: Arial Unicode MS on macOS, Microsoft YaHei UI's Chinese forms on Windows. A line's own kana (or hangul, for Korean) now says which language its Han characters are in, and the run cache keeps them apart. Lines with neither keep the system language's font, and ASCII text is never looked through.

  • Large images draw, at the size they show (zgx-gpu): an image's texture held its whole file (a 4000 by 3000 photo was 48 MB however small it showed), so two large photos passed the 64 MiB budget and the second was left out, or, before 0.1.7, ended the app. Textures now hold an image at its drawn size, resampled as mip levels are, uploaded again as it is drawn larger. The budget is four of the window's frames (at least 64 MiB), and past it images are drawn softer, not left out.

  • An empty image src shows nothing (zgx-script): ui.image, ui.svg and bg_image with src = "" (a picture not chosen yet, often a state's first value) show nothing and report no error, where they read the script's directory and failed with "Is a directory". A missing image's error names the script line asking for it, never a line of .zgx/types.d.luau or another declaration or hidden file that happened to hold the same text.

  • A layer as large as the window draws at its scale (zgx-gpu): each isolated layer had 16 MiB of its own, so one window-sized layer at 2x (2880 by 1800, 20.7 MB) rasterized coarser, softer, and warned of the 64 MiB budget with far less resident. A layer now takes what the budget leaves; the budget is four of the window's frames, at least 64 MiB, counted against what the textures allocate. The warning names the layer and what was resident, allocated and live, once per layer. zgx inspect memory lists each layer (gpu layer: node, pixels, scale, live and allocated bytes, transformed or parked) and layers live beside layers.

  • Monospaced text is upright on Linux (zgx-gpu): cosmic-text's monospace family, Noto Sans Mono, is seldom installed, and its stand-in was whichever fixed-width face came first, on a system with DejaVu its Oblique: every code block and terminal slanted. A family with an upright face is taken now (DejaVu Sans Mono, Liberation Mono, Ubuntu Mono and the like, else any).

  • Chinese text on macOS draws in PingFang (zgx-gpu, the cosmic-text fork): macOS 26 keeps PingFang, its Chinese face, in a private framework, outside the font directories fontdb reads. The fallback lists named only PingFang, so Chinese Han drew in Arial Unicode MS, and traditional and simplified Chinese looked alike. The fork now loads PingFang from where Core Text finds it, if no PingFang is already loaded. Heiti SC and TC, in every macOS, follow it in the lists in case it moves. The system font cache's format is bumped, so the cache is rebuilt once with PingFang in it: 32 more faces, about 0.01 ms more to read it at launch.

  • CJK in monospaced text shows (zgx-gpu, macOS): a monospaced line with Chinese, Japanese or Korean characters fell back to a bitmap-only system font that has no units per em, took infinite width and showed nothing past the first such character. That font is passed by now.

  • A declared window's own state follows it (zgx-desktop, zgx-run, zgx-script): win.active, win.shown and win.size stopped following a declared window for two reasons. WindowContext::on_closed replaced any earlier handler, so zgx run's second handler for a window dropped the first, and with it the effect keeping the state current. And a reload (a hot one, or devtools starting to record) built the window's content with a new state that no host set. Each on_closed handler now runs, in the order given, and a window keeps its own state across loads while it is published.

  • A remembered folder survives an upgrade outside the sandbox (zgx-desktop): on macOS, a folder kept with ui.open_folder { remember } is now a plain bookmark unless the app is sandboxed. A security-scoped bookmark resolves only under the code-signing identifier that made it, and an unbundled app's identifier changes with its build (zgx-run's is cargo's metadata hash), so every remembered folder was forgotten at an upgrade. A sandboxed app still makes security-scoped ones. A grant of the other kind still resolves, and is renewed as the kind the app makes.

  • A plugin's node reads what the app provides above it (zgx-script): ui.use_context in what ui.contribute adds no longer crashes with "Lua instance passed Value created from a different main Lua state". A plain value arrives converted into the plugin's script, a state as the same state (read only, followed live), and a function is an error naming it. Adding before or after the root of a ui.each or ui.list row, which drew nothing, is now an error saying to target an element inside the row.

  • A menu opened by a press stays open when released over its trigger (zgx-desktop, Wayland): when a compositor cut a tall menu and slid it over its trigger, the popup's pointer events (on zgx's own queue) could be handled before the window's release that came first. The release then counted as a drag away, and the menu closed. A window's own buttons and wheel are now heard where the window last saw the pointer.

  • A menu's trigger no longer looks pressed after the menu closes (zgx). A menu opens on the press, so the release went to the menu, and the trigger kept its pressed look while the menu showed and after it closed. A press that opens a popup now ends for what it pressed (it hears a pointer cancel), as the release goes to the popup.

  • Tabs and horizontal scrolls no longer warn of an unresolved height (zgx): with devtools recording, every ui.tabs (and any scroll_x with no height of its own in a row sized by its content) reported "height 100% has nothing to resolve against" for its viewport and content. Those take a definite height or their content's by design, so layout warnings now pass over a scroll's own viewport and content.

  • A scroll view's fade leaves its scrollbar whole (zgx): fade_edges on a scroll view or list with a scrollbar (Luau's fade = { 64, 64 } with scrollbar = true) faded the scrollbar's thumb with the rows, as it passes the fade to all its children. The scrollbar now paints outside its own view's fade; a fade around the view still fades both.

  • Coarse curved meshes no longer shadow themselves in speckles (zgx-3d): where a curve turns from the sun, its flat faces fall behind its smooth normals and caught their own shadow as acne; the shadow lookup now moves off the surface further the more it turns away. A shadow still starts at the base of what casts it, however low the sun. The model example's floor sits just below a model's base, where a model's own floor fought it in speckles.

  • Rounded span backgrounds round on their own corners (zgx-gpu): a span's rounded background (TextSpan::radius, Luau ui.span { bg, padding, radius }, an inline code chip) rounded only the corners that lay on its text's own edges, so a chip mid-line was square, as was each piece of a wrapped one. Each piece now rounds on its own box: a chip wrapped across lines rounds each line's piece on its own ends, as CSS's box-decoration-break: clone.

  • Ctrl+C reaches a terminal's program on Windows whatever started the app (zgx-terminal): Windows passes a parent's choice to ignore Ctrl+C on to its children, so an app started by one (an agent's shell, a service, a launcher) started shells where Ctrl+C never interrupted anything. A session restores Ctrl+C handling before it starts its program.

  • Screen readers hear all of a terminal's new output, and not its echo (zgx-terminal): an engine-drawn terminal told readers of new output by setting its live region at each read, and output read in two parts before the frame's accessibility update (a command's output, then the prompt after it) was heard as its last part alone: Orca said $ and never the output. It now says everything read since its last update with the next frame's. And the shell's echo of each typed character was read out, once a read with nothing new had dropped what was typed: what was typed now waits for its echo.

  • A terminal names the program in front after it execs another (zgx-terminal): an engine-drawn terminal kept the name it first read for a foreground process as long as the process's pid stayed in front, but a process keeps its pid when it runs another program in its place. So the shell, read in the moment between its session forking it and its running, could be named after the app for the whole of a quiet command (sleep 30), and exec less went on showing the shell. The name is now read again at each check, and the check runs once output settles (a moment after the latest output, not the first of a burst), so a command that goes quiet at once, like sleep 30 typed at a prompt, is named too. Checks still follow output alone: nothing polls.

  • ⌘Z no longer sticks in a field the app normalises (zgx, zgx-script): undo went back to what was typed, the app normalised it again, and that became a new step. What the app makes of an edit now joins that edit, so undo goes past both (TextEditor::answer_next).

  • A drag begun as the previous drop finishes isn't lost on Wayland (zgx-desktop): the compositor gives the pointer back at a drop, before the drop's target finishes with it. A drag started then (a tab, say) was ended by that earlier drop's end, with a button release it never had. It now goes on, and goes to the compositor once the earlier drop is done. Known issue: until then it can't leave its window, so let go within that moment (a few milliseconds, longer for a slow target), it drops nothing (#1259).

  • A web page's tree reaches screen readers on Linux on a busy machine too (zgx-desktop's webkitgtk): the page's box embedded the page's accessible tree only if WebKit had named it by the time the page loaded; now it does whenever WebKit names it.

  • A shortcut a web page leaves alone reaches the app on a busy machine (zgx-desktop's webkitgtk, Linux): the key came back from WebKit's web process with the modifiers held when it answered, not when it was pressed, so Ctrl+K let go of quickly reached the app as K and no shortcut took it.

  • An input method's candidates show under a web page's caret on a busy machine (zgx-desktop's webkitgtk, Linux): IBus over XIM forgets the spot as a composition begins, and a page's caret comes from WebKit's web process, sometimes after the candidates had shown, which then stayed at the window's bottom left. The window gives the spot again as a page's composition begins, and tells the input method each caret the page reports as it comes, not at its next frame.

  • Web Inspector opens in a window of its own on Linux, however large the page (zgx-desktop's webkitgtk): WebKitGTK docked the inspector inside a large enough page, where it drew in the page's frames but heard none of its input. It is now detached as WebKit docks it, as its own undock button would, before the page lays out around it.

  • Video and audio play in a web page on Linux (zgx-desktop's webkitgtk): WebKitGTK took a page in a GtkOffscreenWindow for one in no window and started no media there, so no <video> or <audio> ever loaded and an AudioContext stayed suspended. A page's window is now zgx's own offscreen window, which WebKitGTK counts as a window; WebM and Ogg play with the GStreamer plugins WebKitGTK depends on, H.264 with gstreamer1.0-libav.

  • A window's content fills it (zgx-script): the content of a ui.window or an item's window of ui.windows took its own size, so a detail window's column sat in its top-left corner and a ui.tabs in it fell back to a scroll view's default 320 by 240. It now fills its window as the app's own window's root does: across, as a block fills its parent, and down with h_full.

  • A ui.tabs panel can fill the tabs (zgx-components): grow and h_full on a panel's root had nothing to fill, so an editor in a tab stayed at its default size, with layout warnings.

  • A glTF file requiring Draco or meshopt compression says so: its geometry can't be read yet, and it loaded as an empty model with no error.

  • zgx test drives the desktop and the window's size (zgx-script): mount() has a clipboard and file dialogs that answer as the test says (save_to, pick, write_file, read_file, clipboard, copy), so an Export or Import button can be tested instead of failing with "no platform here", and app:resize(width, height) lays out at a new size, ui.window.size following. TestApp::try_with_desktop for Rust tests.

  • The first undo no longer empties a controlled field (zgx-script): a ui.input or ui.textarea with value = function took its text just after mounting, as an edit, so ⌘Z blanked it and on_change told the app so.

  • A capture of a window's frame shows its loops and caret (zgx-gpu; macOS). zgx inspect captures and Ui::snapshot read the frame Metal drew, so what Core Animation plays over it (a baked loop, the blinking caret) was missing: an agent saw a page with its spinner gone. They now draw it in, at its current frame.

  • A small looping animation no longer keeps a window drawing (zgx-gpu, zgx-script; macOS). A spinner or pulsing dot declared with anime.animate { loop = true, frameRate = … } on opacity or shaderTime drew a frame each tick, and any drawn frame keeps about 176 MB of Metal driver memory for 8–13 s on M5 Macs, so one spinner held it for as long as it spun. Such a loop is now drawn once into a small sheet and played by Core Animation: no frames, no wakes. A gallery page with a spinner went from ~340 to ~170 MiB, and app + WindowServer CPU fell 1.7–1.9 points at 60 and 120 Hz. Nothing changes in an app: a loop that a layer couldn't show exactly (cut by a clip or a fade's band, painted over, under a layer, in a popup, large, or watched by a script) draws as it did, and in a trace build zgx inspect switch baked_loops off turns it off.

  • Pages of flex containers peak lower (zgx): each container on the advanced layout path gets a layout tree the size of its children rather than taffy's 16 slots, about 4 MB less at the peak on a 21-page gallery, 0.48 → 0.12 MB allocated per page switch at that site.

  • zgx check reports unknown members of ui (zgx-script): ui.window's type was a function intersected with a table, which Luau reads as never, and that quieted every lookup on ui: a misspelled ui.nope passed strict mode and failed as attempt to call a nil value when it ran. A misspelled option in a ui.window { … } table is zgx lint's window-option.

  • A list being shrunk no longer flips its height for ever (zgx): a size within a 1024th of a point of the last one told is rounding, not movement, and isn't told. Sums at a column's scale could land on neighbouring floats, a reader of the size dirtied layout, and it landed on the other: layout never settled. It took a list in a tight column (a zoomed sidebar) with a fractional neighbour (a fold animating).

  • A reload frees the script it replaces (zgx-script): an anime animation, timeline, draggable or scroll link held a strong handle to the script's own Luau state from inside it, so the state never closed and each hot reload leaked all of it. On a gallery with 15 MB of script heap, 100 reloads took the heap from 54 MB to 2.7 GB; now they stay between 60 and 95 MB, every old state closed.

  • A panic no longer ends hot reload (zgx, zgx-script): a panic while reloading shows as a script error does and the next save reloads, where the watching task went on failing with `async fn` resumed after panicking until the app was relaunched. A task that panics in LocalExecutor::tick goes, and the tasks after it stay ready.

  • A ui.list with sticky rows takes key, scrollbar and its edge callbacks (zgx-script): key with sticky was refused, and scrollbar, overscroll, on_end and on_start panicked or failed on the wrapper around the list. A grouped list with keyed rows and sticky headers works: a sticky row is built as its row is, and follows its key as the list changes.

  • A ui.list of data takes heights (zgx-script): a grouped list, with sticky if it likes, shows its items as they change: an edited item's row builds again. Rows given heights by key alone are built once a key, so an edit didn't show.

  • An app left alone gives memory back (zgx-desktop, zgx-script): as the window goes idle (1.5 s after its last frame), a script host collects its scripts' garbage, drops the decoded pictures no node shows (kept, up to ScriptHost::image_cache's budget, while the app is in use), and the allocator returns what was freed (mi_collect with the mimalloc feature, malloc_zone_pressure_relief on macOS, malloc_trim on Linux). Zeron's gallery, 200 pages browsed and left 15 s: 237–265 MB → 207–209 MB. ScriptHost::collect_garbage collects now; zgx::idle::on_idle registers what else a host should give back.

  • Luau's free pages leave memory as an app goes idle (zgx-mlua, zgx-script): Luau frees a 16 KB page only when its last object goes, and the program's allocator kept such pages in larger runs it returns only whole. With the mimalloc feature they now come from a pool of their own, and each free page goes back to the system as a host goes idle (mlua::release_free_pages). Zeron's gallery, 200 pages browsed and left 15 s: 197–204 MB → 173–177 MB.

  • An animation started while only unseen loops played starts on the next frame (zgx-script): the engine, then looking a few times a second, started it up to 250 ms late and in one jump (a sidebar's width animating 286 → 542 in one frame). A clip's first frame now advances it one frame at most.

  • Layout that never settles no longer ends the app (zgx, zgx-desktop, zgx-script): a window keeps the layout the last of its 64 passes left, tells nothing more of its geometry, and goes on, taking input. It reports once, naming the nodes that still moved (@12, as zgx inspect does), on stderr, in the window's banner, and to the new zgx::issues::on_issue and ScriptHost::on_error. Whenever the layout changes it tries again in at most 16 passes. Ui::try_prepare_frame still returns LayoutFeedbackError unless a host calls Ui::contain_layout_feedback, as window hosts do (what an app keeps running through).

  • ui.each in a scroll_x lays out across (zgx-script): its rows stacked in a column there.

  • macOS: with zgx-desktop's mimalloc feature, the program's heap shows in vmmap, footprint and Activity Monitor as "Memory Tag 240", not "IOAccelerator". mimalloc's default tag, 100, is the one macOS names IOAccelerator, so an app's heap read as GPU memory: in one app 107 MB of "IOAccelerator" was its heap. MIMALLOC_OS_TAG still overrides it.

  • ui.split works without size, a state of its own at 280 points; zgx lint's unknown-token names what a token's group holds when nothing is close ($text.muted: there is $text.primary, $text.secondary…) (zgx-script).

  • An input bound to a state calls on_commit (zgx-script): ui.input { value = draft, on_commit = add } heard nothing on Enter, as only a controlled input (value = function) told it. It now hears the text on Enter, and on leaving the input changed since it was focused, as a controlled input does.

  • A scroll view, list or text area can keep a gesture at its edges (zgx, zgx-script): overscroll = "contain" (View::overscroll_contain, CSS's overscroll-behavior: contain) on ui.scroll, ui.list, ui.input and ui.textarea. A wheel or trackpad gesture that starts over the view stays with it at its edges, momentum included, so the scroll views around it neither move nor stretch (a transcript inside a page). "auto", the default, hands what it can't scroll on as before (scrolling).

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

Known issues

  • On Wayland, a drag begun as the previous drop finishes can't leave its window until that drop is done: let go within that moment (a few milliseconds, longer for a slow drop target) and it drops nothing (#1259).
  • A headless host that measures text with TextServices alone (no renderer) never trims its text caches: prepared text grows to its 32 MB budget and the shaped-word cache keeps growing. Windowed apps are unaffected. Fixed in 0.1.8 (#1293).