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.
- Scene3D
Header - 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,wis the fade width at both side edges.arg0 == 1: a vertical band — alpha ramps in overwpx fromyand, whenh > 0, ramps out overwpx approachingy + 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/yare the projected world origin,wis screen-space spacing,his line thickness,coloris the minor grid color,arg0is the major-axis color, andarg1is the horizontal edge-fade width asf32::to_bits(). - CANVAS_
TILE_ FIELD - A finite, dense canvas field evaluated in O(pixels), not O(items).
x/yare the projected origin,w/hare projected item spacing,arg0packs columns/rows as twou16s, andarg1is 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/yare the center,wthe ring radius,hthe dot radius,colorthe base dot color,arg0the accent color, andarg1the fill fraction in [0, 1] asf32::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/yare the top-left,wthe dot pitch in pixels,hthe dot radius,colorthe lit dot color;arg0/arg1address UTF-8 bytes in the scene text buffer exactly likeTEXT. Advance is 6 dots per glyph. - EVENT_
ACTION - EVENT_
CLOCK - Wall-clock anchor, sent once at startup in interactive mode:
xis the host’s local seconds since midnight when the surface started,yis 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:
xis the layer index from the guest’ssurface_layers_ptrlist. 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_setand sends this event withx= 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):
xis the row index fromsurface_list_ptr,ypacks the toggled control’s logical-pixel center as(x << 16) | yso 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.
xis a bitset ofRENDER_CAPABILITY_*values andyis 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.
xis 1 for a light background and 0 for dark;ypacks the background as0xRRGGBB. 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.
xis the percent (100 = 1:1);x <= 0requests fit-all. Hosts send it from chrome such as the terminal-cell zoom dropdown; guests that exposesurface_zoom_percentshould 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.arg0is the first glyph-entry index,arg1the entry count, andx/y/w/hbecome 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.arg0is a byte offset in that host-owned atlas andarg1packs 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.
arg0is the guest byte pointer andarg1packs 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.colorpacks effect state asreveal:u8 | frame:u8 | seed:u16from 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.
arg0is an opaque handle granted by the host; model bytes never enter guest memory. The command rectangle is the destination viewport andarg1is 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_3Dpackets. - ROUND_
RECT - SCENE_
3D - A bounded native-rendered 3D scene packet.
arg0is the guest byte pointer andarg1is 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.
arg0is one of theVIEW_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_REGIONcommands. - VIEW_
GESTURE_ PAN_ 2D - Backward-compatible whole-viewport 2D pan.
- VIEW_
GESTURE_ PAN_ 2D_ SCOPED - 2D pan restricted by matching
VIEW_GESTURE_REGIONcommands. - 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