x.multiwindow

x.multiwindow is the low-level multi-window layer used by the gg multi-window facade. It owns native window lifetimes, backend selection, per-window events, owner-thread dispatch, and optional render scheduling.

Most application code should use gg with -d gg_multiwindow. This module is intended for the gg facade, backend work, and callers that need direct control over native windows and rendering setup.

Scope

The module provides:

• an App registry for multiple native windows;
• generation-checked WindowId handles;
• backend capability reporting and backend selection;
• lifecycle events routed to a specific window;
• backend-neutral input events routed to a specific window;
• an owner-thread job queue for cross-thread work;
• an opt-in render scheduler and opaque transaction declarations.

It does not provide layout, widgets, text rendering, high-level input semantics, or a default event loop. The gg facade supplies the higher-level loop, gg.Event mapping, and drawing API.

Creating an App

import x.multiwindow

mut app := multiwindow.new_app(backend: .mock, queue_size: 128)!
defer {
    app.stop() or {}
}

win := app.create_window(title: 'Tool', width: 320, height: 200)!
info := app.window_info(win)!
println('${info.title}: ${info.width}x${info.height}')

multiwindow.new_app() uses the values in Config. The low-level default backend is .mock; .auto must be requested explicitly. The gg facade has its own configuration and defaults to .auto.

Config.app_id supplies the native application identity. It is currently marshalled to Wayland as the xdg_toplevel app id; an empty value uses v.x.multiwindow. Other backends currently ignore it.

Config.require_renderer: true asks the selected backend to initialize its renderer during new_app(). The render API requires that creation-time request and Capabilities.explicit_swapchain; x.multiwindow does not lazily initialize a renderer later.

Backend Selection

BackendKind values are:

• .mock: deterministic in-process backend for tests and event-only code;
• .x11: Linux X11 backend, compiled only with -d x_multiwindow_x11;
• .wayland: Linux Wayland backend, compiled only with -d sokol_wayland;
• .appkit: macOS AppKit backend;
• .win32: Windows backend;
• .auto: resolve to a concrete backend.

The .auto policy is platform and environment dependent:

• Windows selects .win32.
• macOS selects .appkit.
• Linux with require_renderer: true prefers X11 only when compiled with -d x_multiwindow_x11 and DISPLAY is set, then Wayland when compiled with -d sokol_wayland and WAYLAND_DISPLAY is set.
• Linux without require_renderer prefers Wayland when compiled with -d sokol_wayland and WAYLAND_DISPLAY is set, then X11 only when compiled with -d x_multiwindow_x11 and DISPLAY is set.
• If no native backend is selected, .auto falls back to .mock.

Plain capability probes do not necessarily open a display or create a device. Renderer capability probes and new_app(require_renderer: true) may fail if the display server, graphics device, or platform API is unavailable.

Backend Capabilities

Capabilities describes the selected backend contract:

• multi_window: backend can manage more than one window;
• owner_queue: the owner-thread queue is available;
• explicit_swapchain: the backend can participate in managed explicit-target rendering; it does not expose a public gfx.Swapchain;
• mock, native, x11, wayland, win32: selected platform flags;
• gl, metal, d3d11: active renderer API flags;
• input_events, mouse_events, keyboard_events, text_events, focus_events, drop_events, touch_events: native input classes the backend can actually deliver;
• cursor_shapes: native hover cursor shape updates are supported via set_window_cursor(id, shape). This is independent from native interactive move/resize support;
• interactive_move_resize: native user-driven move/resize can be requested when the running backend has the required handles and current user action;
• native_decorations: native/server-side decorations are effective for the running backend;
• readback: whether the backend exposes at least one readback path. X11 exposes native window capture without a renderer. X11 and Wayland managed image readback require an active GL renderer; with that renderer, window capture is managed by gg from its owned framebuffer. Mock exposes its deterministic window path, while AppKit reports readback only with a ready Metal renderer. Confirm individual operations per window through the gg readback capability query.

Plain capability probes do not necessarily connect to the display server, so runtime optional globals can be unknown before startup and most of those probes report implementation support. For Wayland, use app.capabilities() after new_app() for the authoritative runtime state: drop_events requires a wl_data_device, touch_events requires wl_touch, and interactive move/resize requires a seat. Wayland cursor-shape reporting is stricter: cursor_shapes is true only after a wp_cursor_shape_device_v1 has been created for the active wl_pointer. Wayland requests server-side decorations through xdg-decoration when the protocol is available; the compositor's configure(mode) decides the effective server_side or client_side mode. If server_side is refused or xdg-decoration is unavailable, apps and examples may draw a client-side fallback. Wayland cursor-shape feedback uses wp_cursor_shape_manager_v1 when the compositor exposes it and the seat has a pointer; this keeps cursor theme selection compositor-side. wl_cursor_theme client-side fallback is not implemented, so app.capabilities() reports cursor_shapes == false on Wayland compositors that do not advertise cursor-shape-v1. Fractional framebuffer scaling is used only when both fractional-scale-v1 and viewporter are present; otherwise the backend keeps the integer wl_output scale path. Clipboard requests require a seat and data device, clipboard writes additionally require a current input serial, and portal-parent identifiers require xdg-foreign-v2.

Backend notes:

• Mock supports lifecycle, events, min-size clamping, and the owner queue, but it has no renderer.
• X11 is Linux-only and exists only in builds compiled with -d x_multiwindow_x11. It supports native lifecycle, title updates, X11 size hints, borderless/fullscreen hints, optional EGL/OpenGL rendering, and native size queries after create/resize. Programmatic resize is rejected for non-resizable windows.
• Wayland is Linux-only and exists only in builds compiled with -d sokol_wayland. It requires wl_compositor and xdg_wm_base, supports initially hidden windows through an explicit remap/configure cycle, and replays the window title, app id, owner relation, size constraints, decoration preference, and requested maximize/fullscreen state when a hidden toplevel is shown again. If the compositor or transport does not supply a fresh configure for that show request, the request fails and the window stays hidden and retryable. It currently rejects programmatic resize. Rendering uses Wayland EGL/OpenGL when initialized.
• AppKit is macOS-only. It must start on the main thread and uses Metal when rendering is required.
• Win32 is Windows-only and supports native lifecycle and min-size enforcement. D3D11 rendering requires a Windows build with -d sokol_d3d11; without that flag, lifecycle works but managed renderer calls are unsupported. Renderer startup can still fail if D3D11 device or swapchain creation is unavailable, and DXGI occlusion during present is treated as a skipped frame.

Window Lifecycle

create_window() creates the native/backend window and returns a generation-checked WindowId. The stored WindowInfo uses the actual size reported by the backend after clamping or native size queries, not just the requested WindowConfig.

A modal window must name a live owner from the same app. Ownerless modal configurations are rejected before native creation, whether initially visible or hidden. Destroying an owner destroys its complete owned-window tree in child-first order, so no child outlives the native owner it references.

destroy_window() destroys one live window, or the child-first owner cascade rooted at that window, and emits a destroy event for each window. Destroying the last window does not stop the app. stop() destroys all remaining live windows, marks the app stopped, stops the backend, and closes owner-queue admission.

Window handles are generation checked. A handle for a destroyed slot becomes stale if that slot is later reused.

Owner-Thread Rule

The thread that calls new_app() is the App owner thread. Mutating operations, event draining, registry enumeration, owner-queue draining, and rendering must run on that thread. Calls from another thread fail with:

multiwindow: operation requires the owner thread

Use post() or try_post() to enqueue short callbacks from other threads, then call drain_pending() on the owner thread. drain_pending() runs at most the requested number of jobs and rechecks app status between jobs; if a job stops the app, later queued jobs are not run.

The simple read helpers status(), capabilities(), window_exists(), and window_status() do not enforce the owner-thread check.

Events

Events are explicit. One canonical queue preserves acceptance order across four families: lifecycle, input, service, and readback. Native events are not delivered to user code until the owner thread calls poll_events().

The owner thread can then call:

• poll_events() to collect backend/native events into the App queue;
• drain_events() for lifecycle events;
• drain_input_events() for input events;
• drain_service_events() for service events;
• drain_readback_events() for readback results;
• drain_queued_events() for all four families in their exact global order.

Each specialized drain consumes only the contiguous prefix of its own family. If a different family is at the head of the queue it returns an empty slice and leaves that event, and everything after it, untouched. This prevents a specialized consumer from silently reordering the stream. Use drain_queued_events() whenever cross-family order matters.

Lifecycle event kinds are:

• .window_created: emitted by create_window() with the actual initial size;
• .window_destroyed: emitted by destroy_window(), stop(), or accepted backend destroy notifications;
• .window_close_requested: emitted when the backend reports a close request;
• .window_resized: emitted after resize_window() or accepted backend resize notifications with the actual size.

Backend events for stale or already-destroyed window handles are filtered.

InputEvent is the low-level backend-neutral payload used by the gg facade to rebuild gg.Event for a specific window. Input kinds include key down/up, char, mouse down/up/move/scroll/enter/leave, resize, iconified/restored, focus/unfocus, clipboard paste, file drop, and touch families. Backends report which families are implemented through the capability booleans above; unsupported input classes must remain false rather than being partially emulated.

Native input events that do not already carry a frame counter are stamped by App.poll_events(); all input events accepted in the same poll cycle share that frame_count. Mock/test events can provide an explicit non-zero frame_count, which is preserved.

Current native input support is intentionally capability-scoped:

• Mock can synthesize every input family for deterministic tests.
• Win32 routes mouse, keyboard, text/char, focus, resize, iconified/restored, clipboard paste signals, file drops via WM_DROPFILES, and WM_TOUCH down/move/up touch input. WM_TOUCH handles are read and closed in the window procedure; WM_TOUCH does not expose a cancelled state, so touches_cancelled is not emitted by the Win32 backend unless a future Pointer Input path owns POINTER_FLAG_CANCELED.
• AppKit routes mouse, keyboard, text/char, focus, resize, iconified/restored, clipboard paste signals, and file drops through NSDraggingDestination file URLs. It also routes AppKit NSResponder touch phases; positions come from NSTouch.normalizedPosition mapped into the current framebuffer, with touches_cancelled emitted only for touchesCancelledWithEvent:.
• X11 routes mouse, keyboard, text/char, focus, resize, iconified/restored, and clipboard paste signal input events. Text uses Xlib XIM/XIC with Xutf8LookupString; this covers committed UTF-8 text from the active input method without exposing Xlib objects through the public API.
• X11 receives XDND text/uri-list file drops through inline or bounded ICCCM INCR transfers (1 MiB maximum). It refreshes the inactivity deadline only on transfer progress, never delivers a partial drop, and sends checked XdndFinished replies without turning a vanished source window into a fatal X error. Valid local file:// URIs are queued as routed .files_dropped events with cloned dropped_files.
• Wayland routes pointer, keyboard, text/char through xkb keymap/state, focus, clipboard paste signal, resize input events, touch when the seat exposes wl_touch, and file drops when wl_data_device/wl_data_offer text/uri-list is available. Data-offer payloads are received through a non-blocking fd and drained from the owner poll path; the backend only sends wl_data_offer.finish after a valid copy or move action has been received. Pending drops whose source never closes the transfer fd are rejected and cleaned up after a bounded number of owner poll cycles. A payload exactly at the byte limit is accepted only after EOF confirms that no extra byte remains. Wayland text follows the existing sapp xkb_state_key_get_utf8 model for key presses; full IME/composed text is not implemented. Wayland synthesizes key-repeat from compositor repeat_info/xkb; pointer frame batching is not synthesized yet; event callbacks are routed as the compositor delivers them.
• Native drop and touch input are false unless a backend explicitly reports the corresponding capability. Clipboard paste is an input signal; clipboard contents are not stored on InputEvent.

QueuedEvent is the ordered envelope. Its kind selects exactly one of lifecycle, input, service, or readback, and sequence is the admitted global delivery sequence.

Window Services

Window services are capability-first. Query service_operation_capability(window, operation) on the live app before each optional operation; the running backend result is authoritative. available means the operation can be attempted now, conditional means a compositor, window configuration, or recent user action can still decide it, and unsupported must be handled without calling the operation. The asynchronous bit means the call is not synchronously authoritative; it does not promise a later canonical-queue result. Check state_observable before waiting for a state observation. Wayland minimize is asynchronous with state_observable == false, so no resulting minimized-state observation is guaranteed.

A prepared destroy ticket remains live and can still admit service work, but a new owned window cannot name that closing window until the ticket is rolled back. Once the ticket is sealed, state/capability queries and new service, readback, and native-borrow admissions for that window fail as stale. Already admitted work follows the terminal or cancellation flow, and queued terminals remain deliverable.

Use service_window_state() for the latest observed mapping, visibility, focus, minimized/maximized/fullscreen, mouse-lock, position, and monitor membership state. Unknown fields are explicit. service_monitor_ids() returns currently available generation-checked monitor ids, and service_monitor_info() returns geometry, work area, scale, primary state, and the observation sequence. A removed monitor can become unavailable and a later replacement receives a new generation; monitor names are descriptive and are not identities. A full backend observation can authoritatively report an empty membership and clears older ids; partial state observations preserve the last known membership. X11 refreshes monitor work areas when the root _NET_WORKAREA or _NET_CURRENT_DESKTOP property changes and retains the last complete snapshot when refresh fails. Win32 continues observing complete native monitor snapshots while no managed windows exist and refreshes that snapshot before the next first-window creation. Window membership observations expose only ids from the currently available public monitor snapshot; a staged native refresh becomes visible atomically with its monitor and metrics events.

Clipboard reads and writes return a ServiceRequestId. Completion is a terminal .clipboard service event with .ready, .cancelled, or .failed. Portal-parent export follows the same request-id-to-event flow, but a ready result also owns a ServicePortalLeaseId. Keep that lease alive while the identifier is used and release it explicitly with service_release_portal_parent(). X11 identifiers start with x11:; Wayland xdg-foreign-v2 identifiers start with wayland:. Treat the remainder as opaque. If preparing a replacement Wayland clipboard source fails before selection submission, the previously published clipboard value remains unchanged. Each Wayland clipboard send already accepted by the compositor owns a bounded snapshot of the offered text and can finish independently after selection replacement or source cancellation. Each active X11 clipboard conversion uses an isolated native requestor; late inline, failure, or INCR replies from an earlier conversion cannot terminalize the next request, and failure to start that next conversion is itself terminal. Replies to external X11 requestors, including INCR chunks, use a checked connection so an expired requestor fails that transfer without poisoning later clipboard work. For X11 INCR reads, the advertised length is a lower bound; actual growth is accepted only within the per-request and aggregate clipboard byte limits. Queued clipboard terminal payloads share a 16 MiB, 64-operation bound across backends and remain charged until their service events are delivered or discarded. Destroying an owner processes its descendants child-first. For each destroyed window, pending clipboard and portal requests are cancelled and portal leases are invalidated during sealing, before teardown results can be delivered. Service cancellations precede readback cancellation and the final lifecycle event in the canonical queue; replay does not create another terminal.

Native window handles are not owned by callers. The gg facade exposes them only through a synchronous callback-bounded borrow; the pointer or integer handle must not be stored, returned, or used after that callback. Backend handle shapes are HWND on Win32, NSWindow on AppKit, Display plus Window on X11, and wl_display plus wl_surface on Wayland.

Readback is asynchronous and terminal. The low-level service_request_window_readback() reads the supplied width and height from the framebuffer origin; service_request_window_readback_region() accepts non-negative coordinates and a positive rectangle fully contained in the target. Ready results own top-left RGBA8 pixels with an explicit stride and producing submitted_frame; cancellation or failure has no pixel payload. Pending and queued readbacks share a 256 MiB, 64-operation bound. A producer reserves its tight RGBA8 size before allocation or capture, and that storage remains charged until the terminal event is delivered or discarded. Window destruction and app stop cancel pending work. The user-facing gg facade publishes readbacks through its run callback and the canonical queue rather than a separate gg readback drain. Aggregate Capabilities.readback and per-window capability queries report availability; each request still validates identity, ownership, render-target/sample constraints, and rectangle bounds.

Runtime support differs by backend:

This table is orientation, not a substitute for the per-window runtime query. Optional compositor protocols, EWMH atoms, renderer state, user-action tokens, and window configuration can change an operation's effective support.

Rendering

Rendering is optional. The render-facing source is selected by -d gg_multiwindow or -d x_multiwindow_render; plain lifecycle and .mock imports remain the no-flag isolation case.

The render contract does not expose gfx.Environment, gfx.Swapchain, native drawables, command buffers, RenderFrame, or present authority. It provides owner-thread opaque batch and target leases, backend-issued ready credits, immutable metrics and target snapshots, late target acquisition, one global commit, ordered finalization, and a private recovery anchor. Each acquired target and its stored slot share a nonzero per-window lease epoch; zero, mismatched, rotated, copied, or expired epochs are rejected.

Render-capable windows support exactly sample_count: 1; other sample counts are rejected. For X11 and Wayland GL renderers, gg captures its currently owned framebuffer before presentation and publishes it only after the producing frame is submitted. X11 without a renderer retains native XGetImage window capture, which observes the X server drawable but is not frame-exact compositor capture under XWayland. Both backends also provide managed single-sample GL image readback. These paths produce owned top-left RGBA8 data in the canonical readback queue. Capability queries remain authoritative because support is backend- and renderer-specific; unsupported paths return gg.multiwindow: requested readback is not supported. AppKit provides the same canonical asynchronous delivery when the active renderer is Metal and its private pre-present hook is installed. Rendererless and GLCore33 AppKit builds report both readback operations as unsupported.

The normative graphics references are the V-vendored Sokol API and matching pinned upstream sokol_gfx.h. Backend lifetime and sequencing must also follow DXGI Present, DXGI ResizeBuffers, D3D11 threading, CAMetalLayer, EGL make-current, and EGL swap contracts. Local precedent does not override those lifetime and threading rules.

Relationship With gg

gg.App is the user-facing multi-window facade and is enabled with -d gg_multiwindow. It maps gg types to x.multiwindow and declares the managed sokol.gfx/sokol.sgl surface.

The main facade mapping is:

Application code should stay on one side of this mapping. The facade converts opaque ids and snapshots; it does not transfer ownership of low-level native or render objects.

examples/gg/multiwindow.v is the interactive rendering example, and examples/gg/multiwindow_services.v is the compact capability-first services, queue, borrow, portal, and optional-readback example:

./v -d gg_multiwindow run examples/gg/multiwindow.v
./v -d gg_multiwindow run examples/gg/multiwindow_services.v

For Linux X11 native rendering, including Xvfb runs, add the X11 backend flag:

xvfb-run -a ./v -d gg_multiwindow -d x_multiwindow_x11 run examples/gg/multiwindow.v

For Wayland, build with -d sokol_wayland. The default build can still fall back to .mock when no enabled native backend is available. The example creates two gg windows, handles lifecycle events, and tolerates backends that reject programmatic resize.

examples/gg/multiwindow_render_runtime.v is the unattended renderer probe used by CI. The backend lanes compile it with -d gg_multiwindow and the matching native flag (-d x_multiwindow_x11, -d sokol_wayland, -d sokol_metal, or -d sokol_d3d11), select the backend with V_MULTIWINDOW_PROBE_BACKEND, and launch it through the process-tree watchdog that owns its parent gate. The probe emits {"example":"multiwindow_render_runtime","status":"PASS","cleanup":"complete"} only after renderer and window cleanup completes.

Limitations

• X11 support is compiled only with -d x_multiwindow_x11; without that flag, the X11 backend is unsupported and X11/EGL/OpenGL libraries are not linked by low-level lifecycle or .mock imports. Enabled X11 builds link Xlib, XCB, and the same-client Xlib/XCB bridge; on Debian-family systems install libx11-dev and libx11-xcb-dev (which supply the XCB development dependency).
• Wayland support is compiled only with -d sokol_wayland; without that flag, the Wayland backend is unsupported and Wayland libraries are not linked.
• Wayland programmatic resize is currently unsupported.
• X11 programmatic resize is rejected for non-resizable windows.
• Native app creation can still fail even when plain capabilities report that a backend is supported, for example when a display cannot be opened.
• The mock backend is not a renderer and cannot produce render targets.
• Multi-window render targets support only sample_count: 1.
• X11 native window capture is available without a renderer through XGetImage, with the native XWayland presentation limitation described above. Managed window/image readback on X11 and Wayland requires an active GL renderer and is limited to the framebuffer owned by gg; it is not compositor or desktop capture. AppKit readback requires its active Metal renderer and private pre-present hook. Win32 readback remains unsupported in this tranche.
• The module has no layout, widget, text rendering, or drawing abstraction.

Validation

The no-flag lifecycle/source check is:

./v test vlib/x/multiwindow/multiwindow_test.v

This command is a non-render isolation check; it does not establish native renderer behavior. Renderer proofs run in the dedicated X11, Wayland, AppKit, and Win32 CI lanes. Each lane sets VGG_MULTIWINDOW_RUNTIME_PROBES=1, VGG_MULTIWINDOW_RUNTIME_BACKEND, and V_MULTIWINDOW_PROBE_BACKEND, compiles with its native renderer flags, and executes each test and runtime probe through the process-tree watchdog. The watchdog supplies the private parent gate, enforces the deadline, reaps child processes, and checks the final cleanup JSON.

Real RandR or Wayland output removal/reconnection and external portal-parent consumption by another toolkit or desktop portal require an interactive desktop session and remain manual integration checks.

fn capabilities_for_backend(kind BackendKind) !Capabilities

capabilities_for_backend reports capabilities without creating an App.

fn capabilities_for_backend_with_renderer(kind BackendKind, require_renderer bool) !Capabilities

capabilities_for_backend_with_renderer reports capabilities with the same backend resolution policy used by new_app(...).

fn capabilities_for_config(config Config) !Capabilities

capabilities_for_config reports capabilities without starting an App while respecting Config.require_renderer for .auto backend selection.

fn new_app(config Config) !&App

new_app creates a low-level multi-window App with the mock backend by default.

fn service_monitor_id_from_gg(app_instance u64, slot int, generation u32) ServiceMonitorId

service_monitor_id_from_gg is an internal gg-facade bridge; not user API.

fn service_portal_lease_id_from_gg(app_instance u64, serial u64) ServicePortalLeaseId

service_portal_lease_id_from_gg is an internal gg-facade bridge; not user API.

fn AppKitWindowDrawableReleaseMode.from[W](input W) !AppKitWindowDrawableReleaseMode

fn AppStatus.from[W](input W) !AppStatus

fn BackendKind.from[W](input W) !BackendKind

fn BackendTargetStatus.from[W](input W) !BackendTargetStatus

fn CursorShape.from[W](input W) !CursorShape

fn EglBindingKind.from[W](input W) !EglBindingKind

fn EventDeliveryState.from[W](input W) !EventDeliveryState

fn EventKind.from[W](input W) !EventKind

fn InputEventKind.from[W](input W) !InputEventKind

fn InternalFaultStage.from[W](input W) !InternalFaultStage

fn NativeLifetimeReleaseKind.from[W](input W) !NativeLifetimeReleaseKind

fn NativeLifetimeTicketState.from[W](input W) !NativeLifetimeTicketState

fn NativeLocalValidation.from[W](input W) !NativeLocalValidation

fn NativeOperationAuthorityScope.from[W](input W) !NativeOperationAuthorityScope

fn NativeOperationTraceMilestone.from[W](input W) !NativeOperationTraceMilestone

fn NativeRenderCallSite.from[W](input W) !NativeRenderCallSite

fn NativeRenderDisposition.from[W](input W) !NativeRenderDisposition

fn NativeRenderDomain.from[W](input W) !NativeRenderDomain

fn NativeRenderOperation.from[W](input W) !NativeRenderOperation

fn NativeRenderScope.from[W](input W) !NativeRenderScope

fn NativeRendererHealth.from[W](input W) !NativeRendererHealth

fn NativeWindowBackend.from[W](input W) !NativeWindowBackend

fn PendingServiceKind.from[W](input W) !PendingServiceKind

fn QueuedEventKind.from[W](input W) !QueuedEventKind

fn RenderAcquireStatus.from[W](input W) !RenderAcquireStatus

fn RenderBlockReason.from[W](input W) !RenderBlockReason

fn RenderFinalizeStatus.from[W](input W) !RenderFinalizeStatus

fn RenderRedrawMode.from[W](input W) !RenderRedrawMode

fn RenderWindowRuntimeStatus.from[W](input W) !RenderWindowRuntimeStatus

fn RendererFaultMilestone.from[W](input W) !RendererFaultMilestone

fn RendererShutdownPath.from[W](input W) !RendererShutdownPath

fn ServiceEventKind.from[W](input W) !ServiceEventKind

fn ServiceMappingState.from[W](input W) !ServiceMappingState

fn ServiceMonitorNativeKind.from[W](input W) !ServiceMonitorNativeKind

fn ServiceObservedBool.from[W](input W) !ServiceObservedBool

fn ServiceOperation.from[W](input W) !ServiceOperation

fn ServiceReadbackStatus.from[W](input W) !ServiceReadbackStatus

fn ServiceStatus.from[W](input W) !ServiceStatus

fn ServiceSupportLevel.from[W](input W) !ServiceSupportLevel

fn ServiceTitlebarAppearance.from[W](input W) !ServiceTitlebarAppearance

fn ServiceVisibilityState.from[W](input W) !ServiceVisibilityState

fn WaylandShowProbeAxis.from[W](input W) !WaylandShowProbeAxis

fn WindowDestroyStage.from[W](input W) !WindowDestroyStage

fn WindowResizeEdge.from[W](input W) !WindowResizeEdge

fn WindowStatus.from[W](input W) !WindowStatus

fn X11ClipboardTransferQueue.from[W](input W) !X11ClipboardTransferQueue

type AppJobFn = fn (mut app App) !

AppJobFn is executed later by the owner queue while App is being pumped.

type NativeWindowBorrowCallback = fn (NativeWindowBorrow) !

NativeWindowBorrowCallback is the callback-bounded facade bridge for a borrow.

type RenderBatchFn = fn (RenderBatchLease, []RenderWindowSnapshot) !

type RenderPassFn = fn () !

enum AppStatus {
	running
	stopped
}

AppStatus describes the application lifecycle owned by App.

enum BackendKind {
	auto
	mock
	x11
	wayland
	appkit
	win32
}

BackendKind selects the platform implementation. The .auto policy resolves to a concrete backend before startup/capabilities are reported.

enum CursorShape {
	default
	pointer
	move
	n_resize
	s_resize
	e_resize
	w_resize
	ne_resize
	nw_resize
	se_resize
	sw_resize
	ew_resize
	ns_resize
	nesw_resize
	nwse_resize
	grab
	grabbing
	text
	crosshair
	not_allowed
	resize_all
}

CursorShape identifies a native cursor image for client-side chrome hover feedback. Cursor support is independent from native interactive move/resize.

enum EventKind {
	window_created
	window_destroyed
	window_close_requested
	window_resized
}

EventKind describes core window lifecycle events emitted by the backend.

enum InputEventKind {
	invalid
	key_down
	key_up
	char
	mouse_down
	mouse_up
	mouse_scroll
	mouse_move
	mouse_enter
	mouse_leave
	touches_began
	touches_moved
	touches_ended
	touches_cancelled
	resized
	iconified
	restored
	focused
	unfocused
	suspended
	resumed
	quit_requested
	clipboard_pasted
	files_dropped
}

InputEventKind mirrors the input/event classes exposed by sokol/gg while remaining independent from gg and sokol imports.

enum NativeWindowBackend {
	mock
	x11
	wayland
	appkit
	win32
}

NativeWindowBackend identifies the native handle shape in a scoped borrow.

enum QueuedEventKind {
	lifecycle
	input
	service
	readback
}

QueuedEventKind identifies one of the four canonical delivery families.

enum RenderAcquireStatus {
	ready
	transient_unavailable
}

enum RenderBlockReason {
	none
	no_workload
	not_configured
	frame_callback_pending
	hidden
	minimized
	occluded
	unmapped
	not_viewable
	zero_sized
	resize_pending
	drawable_unavailable
	backend_unavailable
	renderer_failed
}

RenderBlockReason records the backend fact which withheld a ready credit.

enum RenderRedrawMode {
	on_demand
	continuous
}

RenderRedrawMode controls low-level frame eligibility for one window.

enum ServiceEventKind {
	state
	metrics
	capability
	monitor
	clipboard
	portal_parent
}

ServiceEventKind selects the meaningful payload in ServiceEvent.

enum ServiceMappingState {
	unknown
	unmapped
	mapped
}

ServiceMappingState reports native window-hierarchy mapping.

enum ServiceObservedBool {
	unknown
	off
	on
}

ServiceObservedBool distinguishes an unreported value from observed false/true.

enum ServiceOperation {
	show
	hide
	focus
	raise
	position
	minimize
	maximize
	restore
	fullscreen
	clipboard_read
	clipboard_write
	portal_parent
	native_borrow
	mouse_lock
	titlebar_appearance
	image_readback
	window_capture
}

ServiceOperation identifies an optional runtime native-window service.

enum ServiceReadbackStatus {
	ready
	cancelled
	failed
}

ServiceReadbackStatus is the terminal state of one readback request.

enum ServiceStatus {
	ready
	cancelled
	failed
}

ServiceStatus is the terminal state of an asynchronous service request.

enum ServiceSupportLevel {
	unsupported
	available
	conditional
}

ServiceSupportLevel reports whether one runtime service can be attempted.

enum ServiceTitlebarAppearance {
	system
	light
	dark
}

ServiceTitlebarAppearance requests a system, light, or dark native titlebar.

enum ServiceVisibilityState {
	unknown
	hidden
	visible
	occluded
}

ServiceVisibilityState is the latest native visibility observation.

enum WindowResizeEdge {
	top
	bottom
	left
	right
	top_left
	top_right
	bottom_left
	bottom_right
}

WindowResizeEdge identifies the edge or corner used for an interactive, user-driven native resize operation.

enum WindowStatus {
	invalid
	alive
	destroyed
}

WindowStatus describes the lifecycle of a registered window slot.

struct App {
mut:
	config                      Config
	instance_id                 u64
	status                      AppStatus = .running
	stopping                    bool
	backend                     Backend
	windows                     []WindowSlot
	events                      []QueuedEvent
	event_deliveries            map[u64]EventDeliveryState
	next_event_delivery_token   u64 = 1
	event_dispatch_events       []QueuedEvent
	event_dispatch_active       bool
	event_dispatch_index        int
	event_delivery_terminal     bool
	teardown_acceptance_order   []WindowId
	window_finished             map[string]bool
	window_terminal             map[string]string
	frame_count                 u64
	deferred_poll_error         string
	deferred_poll_error_active  bool
	deferred_poll_barrier_token u64
	backend_event_terminal      string
	render_runtime              RenderRuntimeState
	render_bridge               voidptr
	owner_thread_id             u64
	admission_open              bool = true
	admission_epoch             u64  = 1
	owner_callback_depth        int
	next_stop_serial            u64 = 1
	stop_serial                 u64
	stop_prepared               bool
	stop_terminal               string
	pending_stop_errors         []string
	stop_native_retry_passes    u8
	services                    ServiceRegistry
	native_borrow_depth         int
	deferred_native_windows     []WindowId
	deferred_native_stop        bool
	internal_fault              InternalFaultPlan
	state_mutex                 &sync.Mutex        = sync.new_mutex()
	fault_mutex                 &sync.Mutex        = sync.new_mutex()
	owner                       &executor.Executor = unsafe { nil }
}

App owns the low-level multi-window registry and owner queue.

fn (mut app App) begin_window_move(id WindowId) !

begin_window_move starts a user-driven native move for a live window. Backends that require a recent native input serial may reject the request when it is not made from a deliberate user-action path.

fn (mut app App) begin_window_resize(id WindowId, edge WindowResizeEdge) !

begin_window_resize starts a user-driven native resize for a live resizable window.

fn (app &App) capabilities() Capabilities

capabilities reports the selected backend capabilities.

fn (mut app App) create_window(config WindowConfig) !WindowId

create_window creates a backend window and returns its generation-checked id.

fn (mut app App) destroy_window(id WindowId) !

destroy_window destroys a live window and all of its owned descendants in child-first order. The App remains alive even when the final window is destroyed.

fn (mut app App) drain_events() ![]Event

drain_events consumes only the contiguous lifecycle prefix of the canonical queue.

fn (mut app App) drain_input_events() ![]InputEvent

drain_input_events consumes only the contiguous input prefix of the canonical queue. It never skips lifecycle, service, or readback events.

fn (mut app App) drain_pending(max_jobs int) !int

drain_pending executes up to max_jobs queued owner callbacks while the app is running. After stop(), accepted-but-pending callbacks are not executed and this returns multiwindow: app is stopped.

fn (mut app App) drain_queued_events() ![]QueuedEvent

drain_queued_events consumes lifecycle, input, service, and readback events in the exact global order accepted by App.

fn (mut app App) drain_readback_events() ![]ServiceReadbackResult

drain_readback_events consumes only the contiguous readback prefix of the canonical queue. It never skips lifecycle, input, or service events.

fn (mut app App) drain_render_teardown_notices() ![]RenderTeardownNotice

fn (mut app App) drain_service_events() ![]ServiceEvent

drain_service_events consumes only the contiguous service prefix of the canonical queue. It never skips lifecycle, input, or readback events.

fn (mut app App) finish_stop(ticket AppStopTicket, prior_errors []string) !

fn (mut app App) finish_window_destroy(ticket WindowDestroyTicket, prior_errors []string) !

finish_window_destroy is irreversible. It attempts backend cleanup even when earlier package cleanup failed and records one aggregate terminal outcome.

fn (app &App) instance_id() u64

instance_id is process-monotonic and never reused. It stamps every handle, scheduler lease and accepted owner wrapper belonging to this App.

fn (app &App) live_window_ids_for_stop_for_gg() ![]WindowId

live_window_ids_for_stop_for_gg is an internal bridge reserved for the gg facade teardown. It is not a user API and must not be exposed in user README documentation.

fn (app &App) logical_to_pixel_render_rect(id WindowId, metrics_sequence u64, x f32, y f32, width f32, height f32) !(int, int, int, int)

fn (app &App) pixel_to_logical_render_rect(id WindowId, metrics_sequence u64, x int, y int, width int, height int) !(f32, f32, f32, f32)

fn (mut app App) poll_events() !int

poll_events lets the backend route all native lifecycle, input, service, and readback events into the canonical App queue.

fn (mut app App) post(f AppJobFn) !

post submits a short owner-thread callback if queue capacity is available.

fn (mut app App) prepare_stop() !AppStopTicket

fn (mut app App) prepare_window_destroy(id WindowId) !WindowDestroyTicket

fn (mut app App) prepare_window_destroy_for_stop(id WindowId) !WindowDestroyTicket

fn (app &App) render_window_eligible(id WindowId) !bool

fn (app &App) render_window_snapshot(id WindowId) !RenderWindowSnapshot

fn (mut app App) request_redraw(id WindowId) !

request_redraw is thread-safe admission. Accepted foreign wrappers are app/epoch stamped and become cancellation-only work after stop closes admission; x.executor itself remains unchanged.

fn (mut app App) resize_window(id WindowId, width int, height int) !

resize_window requests a native resize and then updates the authoritative App state.

fn (mut app App) rollback_window_destroy(ticket WindowDestroyTicket) !

fn (mut app App) seal_window_destroy(ticket WindowDestroyTicket) !

fn (mut app App) seal_window_destroy_terminal_for_stop(id WindowId) !WindowDestroyTicket

seal_window_destroy_terminal_for_stop is the irreversible fallback used only after normal prepare/seal failed during stop. Validation happens before the slot is sealed; an accepted live generation already owns its fallback serial.

fn (mut app App) service_abandon_window_readback_for_gg(readback ServiceReadbackId, message string) !

service_abandon_window_readback_for_gg is an internal gg-facade bridge; not user API.

fn (mut app App) service_arm_image_readback_pass_for_gg(id WindowId, image_id u32, pass_serial u64, producing_frame u64) !

service_arm_image_readback_pass_for_gg is an internal gg-facade bridge; not user API.

fn (mut app App) service_begin_window_readback(id WindowId) !ServiceReadbackId

service_begin_window_readback reserves a pending low-level readback identity.

fn (mut app App) service_begin_window_readback_with_payload_for_gg(id WindowId, width int, height int) !ServiceReadbackId

service_begin_window_readback_with_payload_for_gg reserves the tight RGBA8 payload before the gg bridge allocates or stages native pixel storage.

fn (mut app App) service_complete_readback(id WindowId, width int, height int, stride int, pixels []u8, submitted_frame u64) !ServiceReadbackId

service_complete_readback creates and immediately publishes one ready RGBA8 result.

fn (app &App) service_cursor_support(id WindowId, shape CursorShape) !ServiceSupportLevel

service_cursor_support reports runtime support for one native cursor shape.

fn (mut app App) service_fail_window_readback(readback ServiceReadbackId, message string) !

service_fail_window_readback publishes a failed terminal result without pixels.

fn (mut app App) service_finish_window_readback(readback ServiceReadbackId, width int, height int, stride int, pixels []u8, submitted_frame u64) !

service_finish_window_readback publishes a ready owned RGBA8 terminal result.

fn (mut app App) service_hide_window(id WindowId) !

service_hide_window requests that a live window become hidden or unmapped.

fn (mut app App) service_maximize_window(id WindowId) !

service_maximize_window requests native maximization.

fn (mut app App) service_minimize_window(id WindowId) !

service_minimize_window requests native minimization.

fn (app &App) service_monitor_ids() ![]ServiceMonitorId

service_monitor_ids returns currently available generation-checked monitors.

fn (app &App) service_monitor_info(id ServiceMonitorId) !ServiceMonitorInfo

service_monitor_info returns the latest snapshot for one monitor generation.

fn (app &App) service_operation_capability(id WindowId, operation ServiceOperation) !ServiceOperationCapability

service_operation_capability reports authoritative runtime support for one operation on one live window. Query it immediately before optional operations.

fn (mut app App) service_raise_window(id WindowId) !

service_raise_window asks the native platform to raise a live window.

fn (mut app App) service_release_portal_parent(id ServicePortalLeaseId) !

service_release_portal_parent releases a ready portal-parent export lease.

fn (mut app App) service_request_clipboard_text(id WindowId) !ServiceRequestId

service_request_clipboard_text starts an asynchronous clipboard read and returns the id matched by a terminal clipboard ServiceEvent.

fn (mut app App) service_request_focus(id WindowId) !

service_request_focus asks the native platform to focus a live window.

fn (mut app App) service_request_portal_parent(id WindowId) !ServiceRequestId

service_request_portal_parent starts an asynchronous native-parent export. A ready event carries an opaque identifier and an explicitly released lease.

fn (mut app App) service_request_window_readback(id WindowId, width int, height int, submitted_frame u64) !ServiceReadbackId

service_request_window_readback requests an origin-based native readback of the supplied width and height and queues one terminal ServiceReadbackResult.

fn (mut app App) service_request_window_readback_region(id WindowId, x int, y int, width int, height int, submitted_frame u64) !ServiceReadbackId

service_request_window_readback_region requests a positive bounded native pixel region and queues exactly one terminal result.

fn (mut app App) service_resolve_readbacks_after_submit_for_gg(id WindowId, submitted_frame u64, submission_succeeded bool) !

service_resolve_readbacks_after_submit_for_gg is an internal gg-facade bridge; not user API.

fn (mut app App) service_restore_window(id WindowId) !

service_restore_window leaves a supported minimized/maximized/fullscreen state.

fn (mut app App) service_rollback_window_readback_for_gg(readback ServiceReadbackId)

service_rollback_window_readback_for_gg removes a pre-allocation reservation when the gg producer fails before any terminal result can own storage.

fn (mut app App) service_set_clipboard_text(id WindowId, text string) !ServiceRequestId

service_set_clipboard_text starts an asynchronous clipboard write and returns the id matched by a terminal clipboard ServiceEvent.

fn (mut app App) service_set_fullscreen(id WindowId, enabled bool) !

service_set_fullscreen requests or leaves native fullscreen state.

fn (mut app App) service_set_mouse_lock(id WindowId, enabled bool) !

service_set_mouse_lock requests or releases relative pointer confinement.

fn (mut app App) service_set_position(id WindowId, x int, y int) !

service_set_position requests a native top-level position when supported.

fn (mut app App) service_set_titlebar_appearance(id WindowId, appearance ServiceTitlebarAppearance) !

service_set_titlebar_appearance requests a supported native titlebar theme.

fn (mut app App) service_show_window(id WindowId) !

service_show_window requests that a live window become mapped and visible.

fn (mut app App) service_stage_image_readback_for_gg(readback ServiceReadbackId, image_id u32, x int, y int, width int, height int, producing_frame u64) !

service_stage_image_readback_for_gg is an internal gg-facade bridge; not user API.

fn (mut app App) service_stage_window_readback_for_gg(readback ServiceReadbackId, x int, y int, width int, height int, producing_frame u64) !

service_stage_window_readback_for_gg is an internal gg-facade bridge; not user API.

fn (app &App) service_window_state(id WindowId) !ServiceWindowState

service_window_state returns the latest native observation for one live window.

fn (mut app App) set_render_workload(id WindowId, enabled bool) !

fn (mut app App) set_window_cursor(id WindowId, shape CursorShape) !

set_window_cursor updates the native hover cursor for a live window when the selected backend reports capabilities().cursor_shapes.

fn (mut app App) set_window_title(id WindowId, title string) !

set_window_title updates the native title and then the authoritative App state.

fn (app &App) status() AppStatus

status reports the application lifecycle state.

fn (mut app App) stop() !

stop destroys live windows, closes owner-queue admission and marks the app stopped. Pending owner callbacks are canceled logically: public drain_pending() refuses to run them after stop().

fn (mut app App) try_post(f AppJobFn) !

try_post submits a short owner-thread callback without waiting for capacity. It follows x.executor's ! contract: queue-full and closed-queue states are returned as errors instead of a bool.

fn (app &App) validate_native_borrow_for_gg(id WindowId, epoch u64) !NativeWindowBackend

validate_native_borrow_for_gg is an internal gg-facade bridge; not user API.

fn (app &App) window_destroy_order(id WindowId) ![]WindowId

window_destroy_order returns a generation-checked child-first owner cascade.

fn (app &App) window_exists(id WindowId) bool

window_exists reports whether id currently points to a live window.

fn (app &App) window_ids() ![]WindowId

window_ids returns live window ids in stable slot order.

fn (app &App) window_info(id WindowId) !WindowInfo

window_info returns a snapshot of the authoritative App-side window state.

fn (app &App) window_infos() ![]WindowInfo

window_infos returns live window snapshots in stable slot order.

fn (app &App) window_status(id WindowId) !WindowStatus

window_status returns the lifecycle status for a valid generation.

fn (mut app App) with_legacy_render_batch(f RenderBatchFn) !RenderBatchOutcome

fn (mut app App) with_native_window_for_gg(id WindowId, callback NativeWindowBorrowCallback) !

with_native_window_for_gg is an internal gg-facade bridge; not user API.

fn (mut app App) with_scheduled_render_batch(f RenderBatchFn) !RenderBatchOutcome

with_scheduled_render_batch opens one authoritative global transaction. The callback is invoked even with no candidates so app-scoped resource work can initialize and advance without a window frame callback.

fn (mut app App) with_teardown_render_batch(f RenderBatchFn) !RenderBatchOutcome

struct AppStopTicket {
	app_instance u64
	serial       u64
}

struct Capabilities {
pub:
	backend                 BackendKind
	mock                    bool
	native                  bool
	multi_window            bool
	owner_queue             bool
	explicit_swapchain      bool
	readback                bool
	d3d11                   bool
	metal                   bool
	x11                     bool
	wayland                 bool
	win32                   bool
	gl                      bool
	input_events            bool
	mouse_events            bool
	keyboard_events         bool
	text_events             bool
	focus_events            bool
	drop_events             bool
	touch_events            bool
	cursor_shapes           bool
	interactive_move_resize bool
	native_decorations      bool
}

Capabilities reports the active backend-wide contract. Optional per-window service/readback queries remain authoritative for operations with runtime state.

struct Config {
pub:
	backend          BackendKind = .mock
	queue_size       int         = 128
	require_renderer bool
	app_id           string
}

Config configures a multi-window App. app_id supplies a native application identity where supported (currently the Wayland xdg-shell app id).

struct Event {
pub:
	kind      EventKind
	window_id WindowId
	width     int
	height    int
}

Event is always routed to a specific WindowId.

struct InputEvent {
pub:
	kind               InputEventKind
	window_id          WindowId
	frame_count        u64
	key_code           int
	char_code          u32
	key_repeat         bool
	modifiers          u32
	mouse_button       int = input_event_invalid_mouse_button
	mouse_x            f32
	mouse_y            f32
	mouse_dx           f32
	mouse_dy           f32
	scroll_x           f32
	scroll_y           f32
	num_touches        int
	touches            [8]InputTouchPoint
	window_width       int
	window_height      int
	framebuffer_width  int
	framebuffer_height int
	dropped_files      []string
}

InputEvent is always routed to a specific WindowId. It carries the full backend-neutral payload needed to rebuild gg.Event in the gg facade.

struct InputTouchPoint {
pub:
	identifier       u64
	pos_x            f32
	pos_y            f32
	android_tooltype int
	changed          bool
}

InputTouchPoint is the backend-neutral representation of one touch point.

struct NativeWindowBorrow {
	app_instance u64
	window       WindowId
	epoch        u64
	backend      NativeWindowBackend
	primary      voidptr
	secondary    u64
}

NativeWindowBorrow is valid only inside the gg facade's synchronous borrow callback. Its handles and epoch must never escape that callback.

fn (borrow NativeWindowBorrow) app_instance_for_gg() u64

app_instance_for_gg is an internal gg-facade bridge; not user API.

fn (borrow NativeWindowBorrow) window_for_gg() WindowId

window_for_gg is an internal gg-facade bridge; not user API.

fn (borrow NativeWindowBorrow) epoch_for_gg() u64

epoch_for_gg is an internal gg-facade bridge; not user API.

fn (borrow NativeWindowBorrow) backend_for_gg() NativeWindowBackend

backend_for_gg is an internal gg-facade bridge; not user API.

fn (borrow NativeWindowBorrow) primary_for_gg() voidptr

primary_for_gg is an internal gg-facade bridge; not user API.

fn (borrow NativeWindowBorrow) secondary_for_gg() u64

secondary_for_gg is an internal gg-facade bridge; not user API.

struct QueuedEvent {
	delivery_token u64
pub:
	sequence  u64
	kind      QueuedEventKind
	lifecycle Event
	input     InputEvent
	service   ServiceEvent
	readback  ServiceReadbackResult
}

QueuedEvent preserves global admission order across lifecycle, input, service, and readback events. kind selects the meaningful payload field.

struct RenderBatchLease {
	app_instance u64
	epoch        u64
	include_all  bool
}

RenderBatchLease is opaque authority for one owner-thread transaction.

fn (lease RenderBatchLease) epoch_for_gg() u64

epoch_for_gg exposes immutable validation data without exposing scheduler mutation or finish authority.

struct RenderBatchOutcome {
	suppressed_callback_target  RenderTargetLease
	suppressed_callback_outcome NativeRenderResult
	suppressed_callback_message string
pub:
	batch_epoch           u64
	committed             bool
	had_gpu_work          bool
	completed_user_passes int
	finalized_submissions int
	error                 string
}

struct RenderMetricsSnapshot {
pub:
	logical_width        f32
	logical_height       f32
	framebuffer_width    int
	framebuffer_height   int
	dpi_scale            f32
	metrics_sequence     u64
	metrics_available    bool
	conversion_available bool
}

RenderMetricsSnapshot contains only backend-observed values. Conversion is unavailable unless the backend can reproduce it for metrics_sequence.

struct RenderTargetAcquisition {
pub:
	status       RenderAcquireStatus
	lease        RenderTargetLease
	snapshot     RenderWindowSnapshot
	block_reason RenderBlockReason
}

struct RenderTargetLease {
	app_instance u64
	batch_epoch  u64
	target_epoch u64
	window_epoch u64
	window       WindowId
}

RenderTargetLease identifies one acquired target without exposing its swapchain, drawable, command buffer, framebuffer, or native handles.

struct RenderTargetSnapshot {
pub:
	target_identity u64
	color_format    int
	depth_format    int
	sample_count    int
}

struct RenderTeardownNotice {
pub:
	window   WindowId
	snapshot RenderWindowSnapshot
	ticket   WindowDestroyTicket
}

struct RenderWindowSnapshot {
pub:
	window               WindowId
	redraw_mode          RenderRedrawMode
	dirty_epoch          u64
	consumed_epoch       u64
	frame_serial         u64
	submitted_frame      u64
	metrics              RenderMetricsSnapshot
	target               RenderTargetSnapshot
	eligibility_sequence u64
	block_reason         RenderBlockReason
	focus_known          bool
	focused              bool
	minimized_known      bool
	minimized            bool
	batch_epoch          u64
}

RenderWindowSnapshot is immutable scheduler and backend state. Batch candidates expose the checked next serial without mutating persistent state.

struct RendererConfig {
pub:
	buffer_pool_size      int = 128
	image_pool_size       int = 1024
	sampler_pool_size     int = 128
	shader_pool_size      int = 128
	pipeline_pool_size    int = 256
	attachments_pool_size int = 256
}

struct RendererInfo {
pub:
	color_format int
	depth_format int
	sample_count int
}

struct ServiceClipboardResult {
pub:
	id     ServiceRequestId
	window WindowId
	status ServiceStatus
	text   string
	error  string
}

ServiceClipboardResult is a terminal clipboard result matched by request id.

struct ServiceEvent {
pub:
	kind          ServiceEventKind
	window        WindowId
	sequence      u64
	state         ServiceWindowState
	metrics       RenderMetricsSnapshot
	operation     ServiceOperation
	capability    ServiceOperationCapability
	monitor       ServiceMonitorInfo
	monitors      []ServiceMonitorInfo
	clipboard     ServiceClipboardResult
	portal_parent ServicePortalParentResult
}

ServiceEvent carries one native state/capability/monitor observation or one terminal asynchronous service result.

struct ServiceKnownRect {
pub:
	known bool
	value ServiceRect
}

ServiceKnownRect distinguishes unavailable geometry from zeroes.

struct ServiceKnownScale {
pub:
	known bool
	value f32
}

ServiceKnownScale distinguishes an unavailable scale from zero.

struct ServiceMonitorId {
	app_instance u64
	slot         int
	generation   u32
}

ServiceMonitorId is an opaque generation-checked monitor identity.

fn (id ServiceMonitorId) str() string

str returns a diagnostic representation of a ServiceMonitorId.

fn (id ServiceMonitorId) app_instance_for_gg() u64

app_instance_for_gg is an internal gg-facade bridge; not user API.

fn (id ServiceMonitorId) slot_for_gg() int

slot_for_gg is an internal gg-facade bridge; not user API.

fn (id ServiceMonitorId) generation_for_gg() u32

generation_for_gg is an internal gg-facade bridge; not user API.

struct ServiceMonitorInfo {
	native_key ServiceMonitorNativeKey
pub:
	id        ServiceMonitorId
	name      string
	geometry  ServiceKnownRect
	work_area ServiceKnownRect
	scale     ServiceKnownScale
	primary   ServiceObservedBool
	available bool
	sequence  u64
}

ServiceMonitorInfo is one immutable monitor-generation observation. name is descriptive; id is the identity and sequence orders accepted updates.

struct ServiceOperationCapability {
pub:
	support              ServiceSupportLevel
	asynchronous         bool
	requires_user_action bool
	state_observable     bool
}

ServiceOperationCapability is the authoritative per-window runtime result for one operation. asynchronous does not promise a later queued result; state_observable says whether callers can rely on a resulting state observation.

struct ServicePortalLeaseId {
	app_instance u64
	serial       u64
}

ServicePortalLeaseId owns a ready portal export until release or window/app teardown invalidates it.

fn (id ServicePortalLeaseId) app_instance_for_gg() u64

app_instance_for_gg is an internal gg-facade bridge; not user API.

fn (id ServicePortalLeaseId) serial_for_gg() u64

serial_for_gg is an internal gg-facade bridge; not user API.

struct ServicePortalParentResult {
pub:
	id         ServiceRequestId
	window     WindowId
	status     ServiceStatus
	lease      ServicePortalLeaseId
	identifier string
	error      string
}

ServicePortalParentResult is a terminal portal export result. A ready event already queued before teardown can carry a stale lease.

struct ServicePosition {
pub:
	known bool
	x     int
	y     int
}

ServicePosition carries coordinates only when known is true.

struct ServiceReadbackId {
	app_instance u64
	serial       u64
	window       WindowId
}

ServiceReadbackId identifies one window-scoped asynchronous readback.

fn (id ServiceReadbackId) app_instance_for_gg() u64

app_instance_for_gg is an internal gg-facade bridge; not user API.

fn (id ServiceReadbackId) serial_for_gg() u64

serial_for_gg is an internal gg-facade bridge; not user API.

fn (id ServiceReadbackId) window_for_gg() WindowId

window_for_gg is an internal gg-facade bridge; not user API.

struct ServiceReadbackResult {
pub:
	id              ServiceReadbackId
	window          WindowId
	status          ServiceReadbackStatus
	submitted_frame u64
	width           int
	height          int
	stride          int
	pixels_rgba8    []u8
	error           string
}

ServiceReadbackResult is admitted and enqueued once. Dispatch can replay it until callback acknowledgment, so handlers must be idempotent. Ready results own top-left RGBA8 bytes and an explicit stride; cancelled/failed results carry no pixels.

struct ServiceRect {
pub:
	x      int
	y      int
	width  int
	height int
}

ServiceRect is an integer native monitor rectangle.

struct ServiceRequestId {
	app_instance u64
	serial       u64
}

ServiceRequestId identifies one accepted asynchronous service request.

fn (id ServiceRequestId) str() string

str returns a diagnostic representation of a ServiceRequestId.

fn (id ServiceRequestId) app_instance_for_gg() u64

app_instance_for_gg is an internal gg-facade bridge; not user API.

fn (id ServiceRequestId) serial_for_gg() u64

serial_for_gg is an internal gg-facade bridge; not user API.

struct ServiceWindowState {
pub:
	mapping      ServiceMappingState
	visibility   ServiceVisibilityState
	active       ServiceObservedBool
	focused      ServiceObservedBool
	minimized    ServiceObservedBool
	maximized    ServiceObservedBool
	fullscreen   ServiceObservedBool
	mouse_locked ServiceObservedBool
	position     ServicePosition
	monitor_ids  []ServiceMonitorId
	// monitor_membership_observed distinguishes an observed empty membership
	// from a partial state observation which did not report monitors.
	monitor_membership_observed bool
	sequence                    u64
}

ServiceWindowState is the latest observed state for one live window. Unknown values were not reported by the backend.

struct WindowConfig {
pub:
	title        string = 'V Window'
	width        int    = 800
	height       int    = 600
	min_width    int
	min_height   int
	resizable    bool = true
	visible      bool = true
	high_dpi     bool = true
	borderless   bool
	fullscreen   bool
	sample_count int              = 1
	redraw_mode  RenderRedrawMode = .on_demand
	owner        ?WindowId
	modal        bool
	// render_workload is set by the gg facade. A window without work is never
	// claimed merely because it was exposed or marked dirty.
	render_workload bool
}

WindowConfig describes one window at creation time. modal requires a live same-App owner and is validated before a native window is allocated.

struct WindowDestroyTicket {
	app_instance u64
	window       WindowId
	serial       u64
}

WindowDestroyTicket is opaque and app/generation/serial checked at every stage. Only an unsealed ticket can be rolled back.

struct WindowId {
	app_instance u64
	slot         int
	generation   u32
}

WindowId is an opaque generation-checked handle to a window.

fn (id WindowId) str() string

str returns a diagnostic representation of a WindowId without exposing its fields as public mutable state.

fn (id WindowId) app_instance_for_gg() u64

app_instance_for_gg exposes immutable identity data needed by the gg facade to reject foreign handles before any local slot lookup.

struct WindowInfo {
pub:
	id                 WindowId
	status             WindowStatus
	title              string
	width              int
	height             int
	min_width          int
	min_height         int
	resizable          bool
	visible            bool
	high_dpi           bool
	borderless         bool
	fullscreen         bool
	native_decorations bool
}

WindowInfo is a snapshot of the authoritative App-side window state.