surface

package
v1.0.260758 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 30, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppSurface 

type AppSurface struct {
	// contains filtered or unexported fields
}

AppSurface hosts an in-process uiapp.App. Panics inside the app are isolated: the window shows an error screen and the rest of the desktop keeps running.

IMPORTANT: SetTitle / MarkDirty must never take s.mu — Handle/Draw hold s.mu and apps call those (e.g. Files reload → SetTitle) which used to deadlock the entire desktop with no panic log.

func NewAppSurface 

func NewAppSurface(id, title string, app uiapp.App, cols, rows int) (*AppSurface, error)

func (*AppSurface) BindHost 

func (s *AppSurface) BindHost(host uiapp.Host, onTitle TitleSink, onClose CloseSink) error

BindHost attaches shell services, then initializes the app (so Host works in Init/hooks). Must not hold Server.mu across this call — apps may OpenPath / Save config.

func (*AppSurface) Close 

func (s *AppSurface) Close() error

func (*AppSurface) HandleInput 

func (s *AppSurface) HandleInput(ev InputEvent) error

func (*AppSurface) ID 

func (s *AppSurface) ID() string

func (*AppSurface) Kind 

func (s *AppSurface) Kind() string

func (*AppSurface) MouseMode 

func (s *AppSurface) MouseMode() int

func (*AppSurface) NotifyFocus 

func (s *AppSurface) NotifyFocus(focused bool)

func (*AppSurface) ProduceDiff 

func (s *AppSurface) ProduceDiff() cell.Diff

func (*AppSurface) Resize 

func (s *AppSurface) Resize(cols, rows int)

func (*AppSurface) Size 

func (s *AppSurface) Size() (int, int)

func (*AppSurface) Snapshot 

func (s *AppSurface) Snapshot() []cell.Cell

func (*AppSurface) Title 

func (s *AppSurface) Title() string

type BellProvider 

type BellProvider interface {
	TakeBell() bool
}

BellProvider reports terminal BEL / attention requests.

type CloseSink 

type CloseSink func()

CloseSink is called when an app requests window close via Host.

type CursorProvider 

type CursorProvider interface {
	Cursor() (x, y int, visible bool)
}

CursorProvider is implemented by surfaces that expose a text cursor.

type ExtAppSurface 

type ExtAppSurface struct {
	// contains filtered or unexported fields
}

ExtAppSurface hosts an out-of-process app: any executable speaking the NDJSON protocol documented in docs/extapp.md over its own stdin/stdout, rather than a Go uiapp.App called in-process. Lets apps be written in any language, at the cost of the process-spawn overhead and a stricter wire contract (every screen_diff must cover the full grid — see the doc). Crash isolation mirrors AppSurface: a child that exits unexpectedly gets a crash screen in its own window, same as an in-process app panicking, rather than taking anything else down.

func NewExtApp 

func NewExtApp(id, command string, args []string, cols, rows int) (*ExtAppSurface, error)

NewExtApp spawns command (with args) and speaks the out-of-process App protocol over its stdin/stdout. The process is running (but not yet initialized — see BindHost) when this returns without error.

func (*ExtAppSurface) BindHost 

func (s *ExtAppSurface) BindHost(host uiapp.Host) error

BindHost attaches shell services and sends the child its startup Init message. Unlike AppSurface.BindHost, this doesn't wait for the child's Ready reply — the child runs in its own process, and blocking window creation on an arbitrary external binary responding promptly would let one slow or hung app stall the whole desktop. The window just shows a blank canvas until the first real screen_diff arrives.

func (*ExtAppSurface) Close 

func (s *ExtAppSurface) Close() error

Close asks the child to exit by closing its stdin (a well-behaved process sees EOF on its next read and exits on its own), then gives it a couple seconds before killing it outright. Safe to call more than once.

func (*ExtAppSurface) HandleInput 

func (s *ExtAppSurface) HandleInput(ev InputEvent) error

func (*ExtAppSurface) ID 

func (s *ExtAppSurface) ID() string

func (*ExtAppSurface) Kind 

func (s *ExtAppSurface) Kind() string

func (*ExtAppSurface) MouseMode 

func (s *ExtAppSurface) MouseMode() int

func (*ExtAppSurface) NotifyFocus 

func (s *ExtAppSurface) NotifyFocus(focused bool)

NotifyFocus mirrors AppSurface's optional NotifyFocus(bool), picked up by internal/server via the same type assertion.

func (*ExtAppSurface) ProduceDiff 

func (s *ExtAppSurface) ProduceDiff() cell.Diff

ProduceDiff drains messages queued by readLoop and applies them: a screen_diff becomes the surface's new cell grid (v1 requires every screen_diff to cover the full grid — see docs/extapp.md — so there's no partial-rect merge to do), title_changed both updates the local title and forwards to the real Host (so the taskbar/window chrome, which reads the window's own title field, updates too), and notify/launch/ open_path/close_window forward straight to Host. RequestClose is dispatched in its own goroutine: Close() re-takes this same mu, so calling it synchronously here (while mu is already held by this very call) would deadlock — the other four Host calls don't re-enter this surface, so they're safe to call directly.

func (*ExtAppSurface) Resize 

func (s *ExtAppSurface) Resize(cols, rows int)

func (*ExtAppSurface) Size 

func (s *ExtAppSurface) Size() (int, int)

func (*ExtAppSurface) Snapshot 

func (s *ExtAppSurface) Snapshot() []cell.Cell

func (*ExtAppSurface) Title 

func (s *ExtAppSurface) Title() string

type GfxSurface 

type GfxSurface struct {
	// contains filtered or unexported fields
}

GfxSurface renders an RGBA image as half-block cells.

func NewGfxSurface 

func NewGfxSurface(id, title, path string, cols, rows int) (*GfxSurface, error)

func NewGfxSurfaceFromImage 

func NewGfxSurfaceFromImage(id, title string, img image.Image, cols, rows int) *GfxSurface

func (*GfxSurface) Close 

func (s *GfxSurface) Close() error

func (*GfxSurface) HandleInput 

func (s *GfxSurface) HandleInput(ev InputEvent) error

func (*GfxSurface) ID 

func (s *GfxSurface) ID() string

func (*GfxSurface) Kind 

func (s *GfxSurface) Kind() string

func (*GfxSurface) ProduceDiff 

func (s *GfxSurface) ProduceDiff() cell.Diff

func (*GfxSurface) Resize 

func (s *GfxSurface) Resize(cols, rows int)

func (*GfxSurface) Size 

func (s *GfxSurface) Size() (int, int)

func (*GfxSurface) Snapshot 

func (s *GfxSurface) Snapshot() []cell.Cell

func (*GfxSurface) Title 

func (s *GfxSurface) Title() string

type InputEvent 

type InputEvent struct {
	Kind   string // key, mouse
	Rune   rune
	Key    string
	Ctrl   bool
	Alt    bool
	Shift  bool
	Bytes  []byte
	X, Y   int
	Button int
	Action string
}

InputEvent is a normalized input event for surfaces.

type MouseModeProvider 

type MouseModeProvider interface {
	MouseMode() int
}

MouseModeProvider reports whether the guest wants mouse events.

type PtyOpts 

type PtyOpts struct {
	Command    string
	Args       []string
	Cols       int
	Rows       int
	Scrollback int
	Title      string // fallback window title when guest OSC title is empty
}

PtyOpts configures PTY spawn.

type PtySurface 

type PtySurface struct {
	// contains filtered or unexported fields
}

PtySurface hosts a shell/TUI in a PTY + libvterm.

func NewPtySurface 

func NewPtySurface(id, shell string, cols, rows, scrollback int) (*PtySurface, error)

func NewPtySurfaceOpts 

func NewPtySurfaceOpts(id string, opts PtyOpts) (*PtySurface, error)

func (*PtySurface) Close 

func (s *PtySurface) Close() error

func (*PtySurface) Cursor 

func (s *PtySurface) Cursor() (x, y int, visible bool)

func (*PtySurface) HandleInput 

func (s *PtySurface) HandleInput(ev InputEvent) error

func (*PtySurface) HasScrollback 

func (s *PtySurface) HasScrollback() bool

func (*PtySurface) ID 

func (s *PtySurface) ID() string

func (*PtySurface) Kind 

func (s *PtySurface) Kind() string

func (*PtySurface) MouseMode 

func (s *PtySurface) MouseMode() int

func (*PtySurface) ProduceDiff 

func (s *PtySurface) ProduceDiff() cell.Diff

func (*PtySurface) Resize 

func (s *PtySurface) Resize(cols, rows int)

func (*PtySurface) ScrollUIState 

func (s *PtySurface) ScrollUIState() (offset, content, viewport int)

func (*PtySurface) SearchScrollback 

func (s *PtySurface) SearchScrollback(query string, towardOlder bool) (found bool, matches int)

func (*PtySurface) SetScrollUIOffset 

func (s *PtySurface) SetScrollUIOffset(offset int)

func (*PtySurface) Size 

func (s *PtySurface) Size() (int, int)

func (*PtySurface) Snapshot 

func (s *PtySurface) Snapshot() []cell.Cell

func (*PtySurface) TakeBell 

func (s *PtySurface) TakeBell() bool

TakeBell reports whether the guest rang the terminal bell since last check.

func (*PtySurface) Title 

func (s *PtySurface) Title() string

type ScrollbackProvider 

type ScrollbackProvider interface {
	ScrollUIState() (offset, content, viewport int)
	SetScrollUIOffset(offset int)
	HasScrollback() bool
}

ScrollbackProvider exposes scrollback for a window chrome scrollbar. Offset is UI-style: 0 = top of history, Max = live bottom.

type ScrollbackSearchProvider 

type ScrollbackSearchProvider interface {
	SearchScrollback(query string, towardOlder bool) (found bool, matches int)
}

ScrollbackSearchProvider searches scrollback and jumps the viewport.

type Surface 

type Surface interface {
	ID() string
	Kind() string
	Size() (cols, rows int)
	Resize(cols, rows int)
	HandleInput(InputEvent) error
	ProduceDiff() cell.Diff
	Snapshot() []cell.Cell
	Title() string
	Close() error
}

Surface produces a cell grid (PTY, native app, or graphical).

type TitleSink 

type TitleSink func(title string)

TitleSink receives title changes from the App SDK Host.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.