Skip to main content

Crate unpeel_surface

Crate unpeel_surface 

Source
Expand description

Experimental native runtime for Unpeel Surface applications.

The crate exposes the renderer, Kitty presenter, terminal-cell chrome, and the complete scene command contract. Input UI is terminal cells; Surface renders display surfaces (canvas, 3D, dot-grid, cached pixels) beneath them. The ratatui module (behind the default-on ratatui feature) provides the small SurfaceLayer/SurfaceView bridge for existing Ratatui applications. Source formats and rasterization engines are application concerns; Surface accepts their cached pixels through HOST_CACHED_RGBA. Native applications normally need only this crate; the internal ABI crate is re-exported here so consumers do not have to depend on it separately.

Modules§

chrome
Terminal-cell chrome drawn on top of the Kitty placement.
connected
Session-owned retained-scene transport shared by native Surface producers, the standalone runtime, and the Ratatui adapter.
damage
Pixel-diff damage bounds between two rendered frames.
font
glyphs
Real text for the command path: a host-side glyph atlas over the bundled Geist font.
guest
kitty
local_view
Shared local presentation for connected canvas and 3D view gestures.
portable_scene
Conversion helpers for retained scenes that reference a host pixel atlas.
ratatui
Preferred application-level primitives for placing a Surface scene behind Ratatui in Rust TUIs.
remote
Versioned retained-scene transport for local-GPU remote presenters.
remote_presenter
Transport-neutral state for retained-scene presenters.
render
ssh
Safe system-OpenSSH command construction for local Surface presentation.
terminal_projection
Compatibility re-export of the renderer-independent protocol crate.
terminal_reconnect
Bounded terminal state needed to resume a full-screen TUI projection.
wgpu_renderer
Portable GPU backend over wgpu (Vulkan on Linux, Metal on macOS, DX12 on Windows) running the canonical Surface WGSL kernel.

Structs§

Command
A deliberately tiny retained-scene command shared by the WASM guest and native host. All fields are little-endian in guest linear memory.
Primitive3D
One analytic primitive owned by a 3D scene packet. The first example uses spheres and oriented boxes; later mesh handles can be additive kinds.
Scene3DHeader
Camera, environment, and packet metadata for one 3D viewport.

Constants§

ABI_VERSION
CANVAS_EDGE_FADE
Multiply the already-composited canvas alpha by an edge mask. Default (arg0 == 0): horizontal, w is the fade width at both side edges. arg0 == 1: a vertical band — alpha ramps in over w px from y and, when h > 0, ramps out over w px approaching y + h, hiding content scrolled toward the top or bottom. Fixed overlays emitted after this command remain unaffected.
CANVAS_GRID
One infinite 2D grid evaluated by the renderer. x/y are the projected world origin, w is screen-space spacing, h is line thickness, color is the minor grid color, arg0 is the major-axis color, and arg1 is the horizontal edge-fade width as f32::to_bits().
CANVAS_TILE_FIELD
A finite, dense canvas field evaluated in O(pixels), not O(items). x/y are the projected origin, w/h are projected item spacing, arg0 packs columns/rows as two u16s, and arg1 is a deterministic visual seed. Individual high-detail items can be layered above this persistent field.
CIRCLE
COMMAND_BYTES
DOT_RING
A dot-matrix ring gauge evaluated in O(pixels), like the grid and tile field. x/y are the center, w the ring radius, h the dot radius, color the base dot color, arg0 the accent color, and arg1 the fill fraction in [0, 1] as f32::to_bits() — accent dots sweep clockwise from 12 o’clock up to the fraction.
DOT_TEXT
Dot-matrix text: the built-in 5x7 font rendered as round dots on a lattice (flip-dot/LED style), with faint “off” dots filling each glyph cell. x/y are the top-left, w the dot pitch in pixels, h the dot radius, color the lit dot color; arg0/arg1 address UTF-8 bytes in the scene text buffer exactly like TEXT. Advance is 6 dots per glyph.
EVENT_ACTION
EVENT_CLOCK
Wall-clock anchor, sent once at startup in interactive mode: x is the host’s local seconds since midnight when the surface started, y is reserved. A clock guest shows (x + time_ms / 1000) % 86400. Headless runs never send it, so renders stay deterministic; guests keep a fixed demo time as the fallback.
EVENT_COPIED
EVENT_KEY_DOWN
EVENT_KEY_END
EVENT_KEY_HOME
EVENT_KEY_PAGE_DOWN
EVENT_KEY_PAGE_UP
EVENT_KEY_UP
EVENT_LAYER_FOCUS
Activate one named layer from host chrome: x is the layer index from the guest’s surface_layers_ptr list. The guest decides how activation changes its application state or view.
EVENT_LIST_SUBMIT
Submit the host-collected input string as a new list entry. The host’s terminal-cell input field owns all editing; on Enter it writes the final UTF-8 string through surface_input_ptr/surface_input_set and sends this event with x = byte length. Hosts never deliver per-keystroke composer state.
EVENT_LIST_TOGGLE
Toggle one row of the guest’s cell list (host-rendered terminal-cell rows over the surface): x is the row index from surface_list_ptr, y packs the toggled control’s logical-pixel center as (x << 16) | y so the guest can anchor pixel effects (sparkles) to the cell the user clicked. Input UI is cells; the surface below draws only effects.
EVENT_POINTER_DOUBLE
EVENT_POINTER_DOWN
EVENT_POINTER_DRAG
EVENT_POINTER_MOVE
EVENT_POINTER_TRIPLE
EVENT_POINTER_UP
EVENT_RENDER_CAPABILITIES
Native renderer capabilities, sent once before the first frame. x is a bitset of RENDER_CAPABILITY_* values and y is reserved. Guests must retain a portable fallback because older hosts do not send this event.
EVENT_SCROLL_DOWN
EVENT_SCROLL_LEFT
Horizontal viewport navigation, usually emitted by a trackpad or by Shift+wheel. Pointer x/y remain available to the guest.
EVENT_SCROLL_RIGHT
EVENT_SCROLL_UP
EVENT_SELECT_ALL
EVENT_THEME
The terminal’s color scheme, sent after the host queries the real background (OSC 11) at startup. x is 1 for a light background and 0 for dark; y packs the background as 0xRRGGBB. Guests that ignore it keep their dark-scheme defaults.
EVENT_ZOOM_IN
Pointer-anchored canvas zoom, normally mapped from Cmd/Ctrl+wheel.
EVENT_ZOOM_OUT
EVENT_ZOOM_SET
Jump the canvas zoom to an absolute level, anchored at the viewport center. x is the percent (100 = 1:1); x <= 0 requests fit-all. Hosts send it from chrome such as the terminal-cell zoom dropdown; guests that expose surface_zoom_percent should handle it.
GLYPH_RUN
Host-lowered antialiased text run. Guests must never emit this directly; they emit TEXT, and the host lowers it against its glyph atlas before upload. arg0 is the first glyph-entry index, arg1 the entry count, and x/y/w/h become the run’s culling bounds in pixels.
GRADIENT
HOST_CACHED_RGBA
Host-lowered cached RGBA content. Guests must never emit this directly; a native host lowers its own payload commands into these draws and uploads the backing pixels via the renderer’s upload_pixel_atlas. arg0 is a byte offset in that host-owned atlas and arg1 packs the source dimensions. It intentionally shares IMAGE_RGBA’s sampling contract.
IMAGE_RGBA
Bounded RGBA pixels copied into guest memory after an explicit host grant. arg0 is the guest byte pointer and arg1 packs source width/height.
IMAGE_RGBA_REVEAL
Guest-owned RGBA pixels revealed through a deterministic animated noise mask. Payload and destination geometry are identical to IMAGE_RGBA. color packs effect state as reveal:u8 | frame:u8 | seed:u16 from most to least significant bits. Hosts evaluate the mask while sampling, so a guest can keep one stable image buffer instead of rebuilding dithered pixels every frame.
LINE
MAX_SCENE_3D_PRIMITIVES
MODEL_3D
Composite one host-owned mesh resource into a 3D viewport. arg0 is an opaque handle granted by the host; model bytes never enter guest memory. The command rectangle is the destination viewport and arg1 is reserved.
MODIFIER_ALT
MODIFIER_CONTROL
MODIFIER_SHIFT
MODIFIER_SUPER
PRIMITIVE_3D_BOX
PRIMITIVE_3D_BYTES
PRIMITIVE_3D_SELECTED
PRIMITIVE_3D_SPHERE
RENDER_CAPABILITY_SPATIAL_3D
The active renderer evaluates analytic SCENE_3D packets.
ROUND_RECT
SCENE_3D
A bounded native-rendered 3D scene packet. arg0 is the guest byte pointer and arg1 is its byte length. The command rectangle is the viewport. Ordinary 2D commands emitted before it show through transparent scene pixels; commands emitted afterward layer above it.
SCENE_3D_HEADER_BYTES
TEXT
VIEW_GESTURE
Declare a portable, renderer-owned view gesture for the current scene. This command draws no pixels. arg0 is one of the VIEW_GESTURE_* modes. A connected presenter may preview that gesture against its retained scene locally, then send one endpoint-equivalent commit to the authoritative app when the pointer is released.
VIEW_GESTURE_NONE
VIEW_GESTURE_ORBIT_3D
Backward-compatible whole-viewport analytic 3D orbit.
VIEW_GESTURE_ORBIT_3D_SCOPED
Analytic 3D orbit restricted by matching VIEW_GESTURE_REGION commands.
VIEW_GESTURE_PAN_2D
Backward-compatible whole-viewport 2D pan.
VIEW_GESTURE_PAN_2D_SCOPED
2D pan restricted by matching VIEW_GESTURE_REGION commands.
VIEW_GESTURE_REGION
Restrict a scoped view gesture to one screen-space rectangle.
VIEW_GESTURE_REGION_EXCLUDE
Region subtracts terminal chrome or another overlay from the allowed area.
VIEW_GESTURE_REGION_INCLUDE
Region contributes to the gesture’s allowed area.

Functions§

image_reveal_state
Pack the effect state consumed by IMAGE_RGBA_REVEAL.
rgba