chore(gui): add AX usage examples

pkg/display/events.go

@@ -13,6 +13,7 @@ import (
 )
 
 // EventType represents the type of event.
+// Use: eventType := display.EventWindowFocus
 type EventType string
 
 const (
@@ -44,6 +45,7 @@ const (
 )
 
 // Event represents a display event sent to subscribers.
+// Use: evt := display.Event{Type: display.EventWindowFocus, Window: "editor"}
 type Event struct {
 	Type      EventType      `json:"type"`
 	Timestamp int64          `json:"timestamp"`
@@ -52,12 +54,14 @@ type Event struct {
 }
 
 // Subscription represents a client subscription to events.
+// Use: sub := display.Subscription{ID: "sub-1", EventTypes: []display.EventType{display.EventWindowFocus}}
 type Subscription struct {
 	ID         string      `json:"id"`
 	EventTypes []EventType `json:"eventTypes"`
 }
 
 // EventServerInfo summarises the live WebSocket event server state.
+// Use: info := display.EventServerInfo{ConnectedClients: 1, Subscriptions: 3}
 type EventServerInfo struct {
 	ConnectedClients int `json:"connectedClients"`
 	Subscriptions    int `json:"subscriptions"`
@@ -65,6 +69,7 @@ type EventServerInfo struct {
 }
 
 // WSEventManager manages WebSocket connections and event subscriptions.
+// Use: events := display.NewWSEventManager()
 type WSEventManager struct {
 	upgrader    websocket.Upgrader
 	clients     map[*websocket.Conn]*clientState
@@ -74,6 +79,7 @@ type WSEventManager struct {
 }
 
 // clientState tracks a client's subscriptions.
+// Use: state := &clientState{subscriptions: map[string]*Subscription{}}
 type clientState struct {
 	subscriptions map[string]*Subscription
 	mu            sync.RWMutex

pkg/menu/menu.go

@@ -2,6 +2,7 @@
 package menu
 
 // MenuItem describes a menu item for construction (structure only — no handlers).
+// Use: item := menu.MenuItem{Label: "Quit", OnClick: func() {}}
 type MenuItem struct {
 	Label       string
 	Accelerator string
@@ -15,16 +16,19 @@ type MenuItem struct {
 }
 
 // Manager builds application menus via a Platform backend.
+// Use: mgr := menu.NewManager(platform)
 type Manager struct {
 	platform Platform
 }
 
 // NewManager creates a menu Manager.
+// Use: mgr := menu.NewManager(platform)
 func NewManager(platform Platform) *Manager {
 	return &Manager{platform: platform}
 }
 
 // Build constructs a PlatformMenu from a tree of MenuItems.
+// Use: built := mgr.Build([]menu.MenuItem{{Label: "File"}})
 func (m *Manager) Build(items []MenuItem) PlatformMenu {
 	menu := m.platform.NewMenu()
 	m.buildItems(menu, items)
@@ -60,12 +64,14 @@ func (m *Manager) buildItems(menu PlatformMenu, items []MenuItem) {
 }
 
 // SetApplicationMenu builds and sets the application menu.
+// Use: mgr.SetApplicationMenu([]menu.MenuItem{{Label: "Quit"}})
 func (m *Manager) SetApplicationMenu(items []MenuItem) {
 	menu := m.Build(items)
 	m.platform.SetApplicationMenu(menu)
 }
 
 // Platform returns the underlying platform.
+// Use: backend := mgr.Platform()
 func (m *Manager) Platform() Platform {
 	return m.platform
 }

pkg/menu/platform.go

@@ -2,12 +2,14 @@
 package menu
 
 // Platform abstracts the menu backend.
+// Use: var platform menu.Platform = backend
 type Platform interface {
 	NewMenu() PlatformMenu
 	SetApplicationMenu(menu PlatformMenu)
 }
 
 // PlatformMenu is a live menu handle.
+// Use: var root menu.PlatformMenu = platform.NewMenu()
 type PlatformMenu interface {
 	Add(label string) PlatformMenuItem
 	AddSeparator()
@@ -17,6 +19,7 @@ type PlatformMenu interface {
 }
 
 // PlatformMenuItem is a single menu item.
+// Use: var item menu.PlatformMenuItem = root.Add("Quit")
 type PlatformMenuItem interface {
 	SetAccelerator(accel string) PlatformMenuItem
 	SetTooltip(text string) PlatformMenuItem
@@ -26,6 +29,7 @@ type PlatformMenuItem interface {
 }
 
 // MenuRole is a predefined platform menu role.
+// Use: role := menu.RoleFileMenu
 type MenuRole int
 
 const (

pkg/webview/messages.go

@@ -6,16 +6,19 @@ import "time"
 // --- Queries (read-only) ---
 
 // QueryURL gets the current page URL. Result: string
+// Use: result, _, err := c.QUERY(webview.QueryURL{Window: "editor"})
 type QueryURL struct {
 	Window string `json:"window"`
 }
 
 // QueryTitle gets the current page title. Result: string
+// Use: result, _, err := c.QUERY(webview.QueryTitle{Window: "editor"})
 type QueryTitle struct {
 	Window string `json:"window"`
 }
 
 // QueryConsole gets captured console messages. Result: []ConsoleMessage
+// Use: result, _, err := c.QUERY(webview.QueryConsole{Window: "editor", Level: "error", Limit: 20})
 type QueryConsole struct {
 	Window string `json:"window"`
 	Level  string `json:"level,omitempty"` // filter by type: "log", "warn", "error", "info", "debug"
@@ -23,46 +26,54 @@ type QueryConsole struct {
 }
 
 // QuerySelector finds a single element. Result: *ElementInfo (nil if not found)
+// Use: result, _, err := c.QUERY(webview.QuerySelector{Window: "editor", Selector: "#submit"})
 type QuerySelector struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
 }
 
 // QuerySelectorAll finds all matching elements. Result: []*ElementInfo
+// Use: result, _, err := c.QUERY(webview.QuerySelectorAll{Window: "editor", Selector: "button"})
 type QuerySelectorAll struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
 }
 
 // QueryDOMTree gets HTML content. Result: string (outerHTML)
+// Use: result, _, err := c.QUERY(webview.QueryDOMTree{Window: "editor", Selector: "main"})
 type QueryDOMTree struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector,omitempty"` // empty = full document
 }
 
 // QueryComputedStyle returns the computed CSS properties for an element.
+// Use: result, _, err := c.QUERY(webview.QueryComputedStyle{Window: "editor", Selector: "#panel"})
 type QueryComputedStyle struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
 }
 
 // QueryPerformance returns page performance metrics.
+// Use: result, _, err := c.QUERY(webview.QueryPerformance{Window: "editor"})
 type QueryPerformance struct {
 	Window string `json:"window"`
 }
 
 // QueryResources returns the page's loaded resource entries.
+// Use: result, _, err := c.QUERY(webview.QueryResources{Window: "editor"})
 type QueryResources struct {
 	Window string `json:"window"`
 }
 
 // QueryNetwork returns the captured network log.
+// Use: result, _, err := c.QUERY(webview.QueryNetwork{Window: "editor", Limit: 50})
 type QueryNetwork struct {
 	Window string `json:"window"`
 	Limit  int    `json:"limit,omitempty"`
 }
 
 // QueryExceptions returns captured JavaScript exceptions.
+// Use: result, _, err := c.QUERY(webview.QueryExceptions{Window: "editor", Limit: 10})
 type QueryExceptions struct {
 	Window string `json:"window"`
 	Limit  int    `json:"limit,omitempty"`
@@ -71,18 +82,21 @@ type QueryExceptions struct {
 // --- Tasks (side-effects) ---
 
 // TaskEvaluate executes JavaScript. Result: any (JS return value)
+// Use: _, _, err := c.PERFORM(webview.TaskEvaluate{Window: "editor", Script: "document.title"})
 type TaskEvaluate struct {
 	Window string `json:"window"`
 	Script string `json:"script"`
 }
 
 // TaskClick clicks an element. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskClick{Window: "editor", Selector: "#submit"})
 type TaskClick struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
 }
 
 // TaskType types text into an element. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskType{Window: "editor", Selector: "#search", Text: "core"})
 type TaskType struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
@@ -90,23 +104,27 @@ type TaskType struct {
 }
 
 // TaskNavigate navigates to a URL. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskNavigate{Window: "editor", URL: "https://example.com"})
 type TaskNavigate struct {
 	Window string `json:"window"`
 	URL    string `json:"url"`
 }
 
 // TaskScreenshot captures the page as PNG. Result: ScreenshotResult
+// Use: result, _, err := c.PERFORM(webview.TaskScreenshot{Window: "editor"})
 type TaskScreenshot struct {
 	Window string `json:"window"`
 }
 
 // TaskScreenshotElement captures a specific element as PNG. Result: ScreenshotResult
+// Use: result, _, err := c.PERFORM(webview.TaskScreenshotElement{Window: "editor", Selector: "#panel"})
 type TaskScreenshotElement struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
 }
 
 // TaskScroll scrolls to an absolute position (window.scrollTo). Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskScroll{Window: "editor", X: 0, Y: 600})
 type TaskScroll struct {
 	Window string `json:"window"`
 	X      int    `json:"x"`
@@ -114,12 +132,14 @@ type TaskScroll struct {
 }
 
 // TaskHover hovers over an element. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskHover{Window: "editor", Selector: "#help"})
 type TaskHover struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
 }
 
 // TaskSelect selects an option in a <select> element. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskSelect{Window: "editor", Selector: "#theme", Value: "dark"})
 type TaskSelect struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
@@ -127,6 +147,7 @@ type TaskSelect struct {
 }
 
 // TaskCheck checks/unchecks a checkbox. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskCheck{Window: "editor", Selector: "#accept", Checked: true})
 type TaskCheck struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
@@ -134,6 +155,7 @@ type TaskCheck struct {
 }
 
 // TaskUploadFile uploads files to an input element. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskUploadFile{Window: "editor", Selector: "input[type=file]", Paths: []string{"/tmp/report.pdf"}})
 type TaskUploadFile struct {
 	Window   string   `json:"window"`
 	Selector string   `json:"selector"`
@@ -141,6 +163,7 @@ type TaskUploadFile struct {
 }
 
 // TaskSetViewport sets the viewport dimensions. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskSetViewport{Window: "editor", Width: 1280, Height: 800})
 type TaskSetViewport struct {
 	Window string `json:"window"`
 	Width  int    `json:"width"`
@@ -148,11 +171,13 @@ type TaskSetViewport struct {
 }
 
 // TaskClearConsole clears captured console messages. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskClearConsole{Window: "editor"})
 type TaskClearConsole struct {
 	Window string `json:"window"`
 }
 
 // TaskHighlight visually highlights an element.
+// Use: _, _, err := c.PERFORM(webview.TaskHighlight{Window: "editor", Selector: "#submit", Colour: "#ffcc00"})
 type TaskHighlight struct {
 	Window   string `json:"window"`
 	Selector string `json:"selector"`
@@ -160,31 +185,37 @@ type TaskHighlight struct {
 }
 
 // TaskOpenDevTools opens the browser devtools for the target window. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskOpenDevTools{Window: "editor"})
 type TaskOpenDevTools struct {
 	Window string `json:"window"`
 }
 
 // TaskCloseDevTools closes the browser devtools for the target window. Result: nil
+// Use: _, _, err := c.PERFORM(webview.TaskCloseDevTools{Window: "editor"})
 type TaskCloseDevTools struct {
 	Window string `json:"window"`
 }
 
 // TaskInjectNetworkLogging injects fetch/XHR interception into the page.
+// Use: _, _, err := c.PERFORM(webview.TaskInjectNetworkLogging{Window: "editor"})
 type TaskInjectNetworkLogging struct {
 	Window string `json:"window"`
 }
 
 // TaskClearNetworkLog clears the captured network log.
+// Use: _, _, err := c.PERFORM(webview.TaskClearNetworkLog{Window: "editor"})
 type TaskClearNetworkLog struct {
 	Window string `json:"window"`
 }
 
 // TaskPrint prints the current page using the browser's native print flow.
+// Use: _, _, err := c.PERFORM(webview.TaskPrint{Window: "editor"})
 type TaskPrint struct {
 	Window string `json:"window"`
 }
 
 // TaskExportPDF exports the page to a PDF document.
+// Use: result, _, err := c.PERFORM(webview.TaskExportPDF{Window: "editor"})
 type TaskExportPDF struct {
 	Window string `json:"window"`
 }
@@ -192,12 +223,14 @@ type TaskExportPDF struct {
 // --- Actions (broadcast) ---
 
 // ActionConsoleMessage is broadcast when a console message is captured.
+// Use: _ = c.ACTION(webview.ActionConsoleMessage{Window: "editor", Message: webview.ConsoleMessage{Type: "error", Text: "boom"}})
 type ActionConsoleMessage struct {
 	Window  string         `json:"window"`
 	Message ConsoleMessage `json:"message"`
 }
 
 // ActionException is broadcast when a JavaScript exception occurs.
+// Use: _ = c.ACTION(webview.ActionException{Window: "editor", Exception: webview.ExceptionInfo{Text: "ReferenceError"}})
 type ActionException struct {
 	Window    string        `json:"window"`
 	Exception ExceptionInfo `json:"exception"`
@@ -206,6 +239,7 @@ type ActionException struct {
 // --- Types ---
 
 // ConsoleMessage represents a browser console message.
+// Use: msg := webview.ConsoleMessage{Type: "warn", Text: "slow network"}
 type ConsoleMessage struct {
 	Type      string    `json:"type"` // "log", "warn", "error", "info", "debug"
 	Text      string    `json:"text"`
@@ -216,6 +250,7 @@ type ConsoleMessage struct {
 }
 
 // ElementInfo represents a DOM element.
+// Use: el := webview.ElementInfo{TagName: "button", InnerText: "Save"}
 type ElementInfo struct {
 	TagName     string            `json:"tagName"`
 	Attributes  map[string]string `json:"attributes,omitempty"`
@@ -225,6 +260,7 @@ type ElementInfo struct {
 }
 
 // BoundingBox represents element position and size.
+// Use: box := webview.BoundingBox{X: 10, Y: 20, Width: 120, Height: 40}
 type BoundingBox struct {
 	X      float64 `json:"x"`
 	Y      float64 `json:"y"`
@@ -234,6 +270,7 @@ type BoundingBox struct {
 
 // ExceptionInfo represents a JavaScript exception.
 // Field mapping from go-webview: LineNumber->Line, ColumnNumber->Column.
+// Use: err := webview.ExceptionInfo{Text: "ReferenceError", URL: "app://editor"}
 type ExceptionInfo struct {
 	Text       string    `json:"text"`
 	URL        string    `json:"url,omitempty"`
@@ -244,12 +281,14 @@ type ExceptionInfo struct {
 }
 
 // ScreenshotResult wraps raw PNG bytes as base64 for JSON/MCP transport.
+// Use: shot := webview.ScreenshotResult{Base64: "iVBORw0KGgo=", MimeType: "image/png"}
 type ScreenshotResult struct {
 	Base64   string `json:"base64"`
 	MimeType string `json:"mimeType"` // always "image/png"
 }
 
 // PerformanceMetrics summarises browser performance timings.
+// Use: metrics := webview.PerformanceMetrics{NavigationStart: 1.2, LoadEventEnd: 42.5}
 type PerformanceMetrics struct {
 	NavigationStart      float64 `json:"navigationStart"`
 	DOMContentLoaded     float64 `json:"domContentLoaded"`
@@ -261,6 +300,7 @@ type PerformanceMetrics struct {
 }
 
 // ResourceEntry summarises a loaded resource.
+// Use: entry := webview.ResourceEntry{Name: "app.js", EntryType: "resource"}
 type ResourceEntry struct {
 	Name            string  `json:"name"`
 	EntryType       string  `json:"entryType"`
@@ -273,6 +313,7 @@ type ResourceEntry struct {
 }
 
 // NetworkEntry summarises a captured fetch/XHR request.
+// Use: entry := webview.NetworkEntry{URL: "/api/status", Method: "GET", Status: 200}
 type NetworkEntry struct {
 	URL       string `json:"url"`
 	Method    string `json:"method"`
@@ -284,6 +325,7 @@ type NetworkEntry struct {
 }
 
 // PDFResult contains exported PDF bytes encoded for transport.
+// Use: pdf := webview.PDFResult{Base64: "JVBERi0xLjQ=", MimeType: "application/pdf"}
 type PDFResult struct {
 	Base64   string `json:"base64"`
 	MimeType string `json:"mimeType"` // always "application/pdf"

pkg/window/layout.go

@@ -11,6 +11,7 @@ import (
 )
 
 // Layout is a named window arrangement.
+// Use: layout := window.Layout{Name: "coding"}
 type Layout struct {
 	Name      string                 `json:"name"`
 	Windows   map[string]WindowState `json:"windows"`
@@ -19,6 +20,7 @@ type Layout struct {
 }
 
 // LayoutInfo is a summary of a layout.
+// Use: info := window.LayoutInfo{Name: "coding", WindowCount: 2}
 type LayoutInfo struct {
 	Name        string `json:"name"`
 	WindowCount int    `json:"windowCount"`

pkg/window/tiling.go

@@ -4,6 +4,7 @@ package window
 import "fmt"
 
 // TileMode defines how windows are arranged.
+// Use: mode := window.TileModeLeftRight
 type TileMode int
 
 const (
@@ -27,9 +28,12 @@ var tileModeNames = map[TileMode]string{
 	TileModeLeftRight: "left-right", TileModeGrid: "grid",
 }
 
+// String returns the canonical layout name for the tile mode.
+// Use: label := window.TileModeGrid.String()
 func (m TileMode) String() string { return tileModeNames[m] }
 
 // SnapPosition defines where a window snaps to.
+// Use: pos := window.SnapRight
 type SnapPosition int
 
 const (
@@ -45,6 +49,7 @@ const (
 )
 
 // WorkflowLayout is a predefined arrangement for common tasks.
+// Use: workflow := window.WorkflowCoding
 type WorkflowLayout int
 
 const (
@@ -59,9 +64,12 @@ var workflowNames = map[WorkflowLayout]string{
 	WorkflowPresenting: "presenting", WorkflowSideBySide: "side-by-side",
 }
 
+// String returns the canonical workflow name.
+// Use: label := window.WorkflowCoding.String()
 func (w WorkflowLayout) String() string { return workflowNames[w] }
 
 // ParseWorkflowLayout converts a workflow name into its enum value.
+// Use: workflow, ok := window.ParseWorkflowLayout("coding")
 func ParseWorkflowLayout(name string) (WorkflowLayout, bool) {
 	for workflow, workflowName := range workflowNames {
 		if workflowName == name {

pkg/window/window.go

@@ -8,6 +8,7 @@ import (
 )
 
 // Window is CoreGUI's own window descriptor — NOT a Wails type alias.
+// Use: spec := &window.Window{Name: "editor", URL: "/editor"}
 type Window struct {
 	Name                string
 	Title               string
@@ -38,6 +39,7 @@ func (w *Window) ToPlatformOptions() PlatformWindowOptions {
 }
 
 // Manager manages window lifecycle through a Platform backend.
+// Use: mgr := window.NewManager(platform)
 type Manager struct {
 	platform      Platform
 	state         *StateManager