class Editor

Registers a face for glyph lookup; returns its id, or nil on failure. Idempotent per (path, pixelSize). System clipboard. Empty when headless.

False while minimized/occluded. The frame loop gates continuous (animation-driven) redraw work on this, since Yoga/cull-rect visibility has no idea the whole window is off-screen.

Which registrar name this panel owns, or empty.

Changes whenever the imported menu does.

Who names GPU resources for the frames this editor produces.

Itself, unless told otherwise — which is what makes an ordinary app unaware that this question exists. A client under a shared renderer assigns the compositor here, once, at startup:

guard let editor = LavaClient.open(title: "My App") else { exit(1) }
editor.resources = compositor      // ids now come from the renderer

Set before loading anything. Ids already stamped into a UIFont or a UIImage are not revisited, so a switch after the fact leaves the resources loaded before it naming things in the wrong process.

Number of open windows. Zero is how an app knows to exit.

Ids of the open windows, in creation order.

Register this window's menu with the session AppMenu registrar.

The same, under an id this process supplies rather than an X11 window id — which is what a compositor client has instead: its surface id, the number the panel hears about when the window takes focus.

Panel-activated MenuID raw string, or empty if the queue is empty.

True if a menu registrar — org.lavaui.AppMenu.Registrar or the canonical com.canonical.AppMenu.Registrar — is on the session bus and canvas was built with libdbusmenu-glib.

Drives this window from a draw arena another process writes, instead of from a DrawList submitted in this one.

The producer creates the arena and this attaches to it, so the order is producer-then-renderer. Returns false if it is missing or its header does not check out.

The same capture as PNG bytes.

For a caller that is not about to put it in JSON — the compositor answering CaptureSurface for a client, where base64 would be a third more bytes on the wire and a decode at the other end, to satisfy a protocol the renderer is not speaking.

Capture the resolve target as PNG (base64). Region in framebuffer pixels; omit or pass w/h ≤ 0 for the full frame. maxSide > 0 downsamples so the longer encoded side ≤ maxSide. Returns (base64, encodedWidth, encodedHeight) or nil on failure.

Closes one window. Every other window, and the device, survive it.

Decodes an image file to RGBA8 without touching the GPU.

Safe to call from a worker thread — that is the whole point. Decoding a JPEG is tens of milliseconds and does not need the device; only the upload does. Returns nil if the file will not decode.

maxPixelSize (0 = native) caps the longer edge. Returned width and height are the size after any downscale, so the caller sizes its texture from these rather than from what the file claimed.

turn is applied after the orientation the file itself declares — the decoder always applies that one — so it composes with what is on screen rather than with how the sensor read out. It is done here and not by the caller so that there is one implementation of turning pixels in the whole system: a viewer that turned a photograph one way on screen and another way into the file it wrote would be wrong in the way nobody notices until the file is saved.

The same decode from encoded bytes already in memory, for an image that never had a path — downloaded, generated, unpacked from an archive.

bytes are the encoded file (PNG, JPEG, …), not raw pixels: the format is sniffed the way it is for a file.

Paths from the most recent .fileDrop event. Valid only while handling that event — the next drop overwrites them.

RGBA8 → baseline JPEG at quality (1-100), always at native size.

For writing a transformed photograph back where it came from. PNG is the better encoder for everything this framework normally does, and the wrong one here: re-encoding a 24-megapixel JPEG losslessly turns six megabytes into a hundred and thirty, which is not what anyone means by "save".

Alpha is discarded — JPEG has none. Do not route an image that uses it through here.

RGBA8 → PNG. maxSide 0 is native.

Current swapchain / framebuffer size in pixels.

Frames published for window that its consumer has not taken yet.

Zero unless this window publishes to another process. See FrameSink.framesInFlight — advisory back-pressure, not a lock.

Whether the engine already has this key resident.

Inject a key event. action: 0 release, 1 press, 2 repeat (GLFW).

Inject mouse button. button is GLFW-style (0 = left).

Inject pointer motion into the same queue as GLFW (layout pixels).

Inject wheel/trackpad delta (notches), same coalescing queue as real scroll.

Inject UTF-8 text as character events (focused text field path).

False while this window is minimized/occluded.

Install face for draw-list text (must match UIFont used for measure).

Load a PNG/JPEG for Image views. Returns a handle or nil on failure. Idempotent per absolute path.

Whose menu to import. 0 shows none.

menuService / menuObjectPath come from the focused window's KDE Wayland AppMenu address when the compositor has one; empty falls back to the AppMenu registrar under windowId — ActiveWindow.registrarId, which is the surface id for Wayland clients and an XID for X11 ones — then to a registrar entry whose DBus sender has pid (Qt5 Wayland).

Own a registrar name and start importing menus. False without a bus.

Opens an engine that lays out and emits frames for another process to draw: no Vulkan, no window, no GPU.

Everything above this — LavaWindow, the view tree, layout, emit — is unchanged and unaware. That is the point: a client is not a second frame loop, it is the same one with the parts that need a screen answering honestly that they have none. renderFrame succeeds and draws nowhere, capturePngBase64 returns nil, loadImage returns nil (see below), and the rest behaves exactly as it does in a window.

Two things a client cannot answer for itself and must be told:

• Size. There is no surface to measure, so setClientSize is the only way it learns one, and the initial width/height here are a guess until something says otherwise.
• Input. The inject* entry points are the whole input path, not a test affordance layered over a real one — which is what lets the agent server drive a client with no compositor on the other end.

Known gaps, both by design and both scoped as later work: images fail to load (a texture id is per-process and there is no RegisterFont equivalent for images yet), and registerFont hands out ids from a local table that means nothing to a renderer elsewhere.

Opens an additional window. Returns its id, or nil on failure.

It starts hidden. Draw a frame into it, then setVisible(true, window:) — showing a window before its first frame presents an undefined swapchain image, which looks like a flash of garbage.

Raw input: mouse, resize, key (see InputEventKind).

Queues an event that arrived already formed — from a renderer in another process — rather than one derived from a device here.

The only way some events can reach a client at all: .resize, .nodeHover, .nodeScroll and .nodeAnimationDone are answers a renderer produces by looking at its own retained scene, and a client has no scene and no device to synthesize them from. A .resize is also state, not just an event, and updates what framebufferSize reports from here on.

Thread-safe, like every input entry point — the queue is the one thing in a window that has always been touched from more than one thread. Callers still have to wakeEventLoop() if the loop may be parked.

Sends this window's frames somewhere other than the engine — a shared arena another process renders from.

Takes effect for DrawLists built after it, so a client installs the sink before LavaApp.run rather than during. A list already holding the old sink keeps writing to it, which is the safe way round: the alternative is swapping the storage out from under a frame that is halfway emitted.

Drive the window from this thread. timeout < 0 blocks until an event arrives, 0 polls, > 0 waits at most that long. Blocking is what keeps an idle UI at zero CPU while still waking immediately on input.

Decode on a worker, upload on the main thread.

The split is not an optimization, it is a requirement in both directions: decoding a JPEG is tens of milliseconds and would stall the frame, and uploading touches the Vulkan device, which is the main thread's alone.

Render and present one frame.

Renders several windows at once, one thread per window.

A frame is mostly the window's own — its command pool, its fences, its buffers — but not entirely: picking up a resize, growing the shared glyph atlas and freeing images no window references any more all reach across every window at once. Those run here, before and after the group, because none of them is safe while a window is recording.

Rendering one window at a time needs none of this — renderFrame brackets itself.

Ask the frame loop to exit (GLFW should-close). Safe from menu actions.

Offers a wheel notch to the retained scroll containers under the pointer, after nothing in this process wanted it.

The renderer normally keeps the wheel — that is what lets a list scroll while this process is busy — and only forwards the event where a node declared a handler of its own. Whether that handler takes a given notch is a question only this process can answer, so when the answer is no, the event goes back. Returns whether anything moved.

Tells a client window how big it is, queueing the .resize its tree needs to re-lay-out. No-op on a window that has a renderer, which measures its own surface instead.

The pointer image over this window.

Windowed only: a client has no pointer to set, and asks the compositor instead (CursorBridge). No-op there rather than an error, so the same call site works in both modes.

Constrains interactive resizing of a local window. Zero means no minimum on that axis. Client surfaces use their compositor host.

Whole-window camera. Layout and Yoga stay at zoom=1; the quad shader applies center-zoom then pan. Hit-tests must unproject first.

Opens key's DBusMenu. False when the item exports none — activate it instead.

Own org.kde.StatusNotifierWatcher. False if the name is taken or there is no session bus.

Consumes "this window needs redrawing for a reason of its own".

The third repaint signal, alongside "a producer published" and "input arrived": the renderer moves scene nodes itself — a scroll today — and when it does, nothing is published and nothing is queued, because the point of a retained tree is that the producer is not involved.

Drops one reference to a loaded image.

The GPU memory is not normally freed here. At zero references the image goes dormant, keeping its pixels and its id so reloading the same key costs nothing. Eviction from there is LRU, and never touches an image a window's current frame still names. Standalone images are evicted against a byte budget (LAVA_IMAGE_CACHE_MB, 256 by default); atlased ones against atlas occupancy, since a cell is far too small to move a byte budget but the cells themselves run out. Allocated atlas pages stay resident either way.

Uploads pre-decoded pixels. Main thread only — it touches the device.

key is the texture identity (see UIImage.cacheKey); path is the file it came from, and defaults to key for callers that decode at native size and need no distinction.

Unblock a waiting pumpEvents from any thread (agent socket watcher).

Whether this window has been asked to close (its titlebar X, a WM request). The caller decides what that means — closing the last window usually ends the app, closing any other is just closeWindow.

False for a window that is already closed: "asked to close" and "does not exist" are different questions, and windowCount answers the second.