widget

type Canvas interface {
	// Clear fills the entire canvas with the given color.
	Clear(color Color)

	// DrawRect fills a rectangle with the given color.
	DrawRect(r geometry.Rect, color Color)

	// StrokeRect draws the outline of a rectangle.
	//
	// The strokeWidth specifies the line thickness in logical pixels.
	StrokeRect(r geometry.Rect, color Color, strokeWidth float32)

	// DrawRoundRect fills a rounded rectangle with the given color.
	//
	// The radius specifies the corner radius.
	DrawRoundRect(r geometry.Rect, color Color, radius float32)

	// StrokeRoundRect draws the outline of a rounded rectangle.
	StrokeRoundRect(r geometry.Rect, color Color, radius float32, strokeWidth float32)

	// DrawCircle fills a circle with the given color.
	//
	// The center and radius specify the circle geometry.
	DrawCircle(center geometry.Point, radius float32, color Color)

	// StrokeCircle draws the outline of a circle.
	StrokeCircle(center geometry.Point, radius float32, color Color, strokeWidth float32)

	// DrawLine draws a line between two points.
	DrawLine(from, to geometry.Point, color Color, strokeWidth float32)

	// DrawText draws text within the given bounding rectangle.
	//
	// The fontSize is in logical pixels. The bold flag selects bold weight.
	// The align parameter controls horizontal alignment.
	DrawText(text string, bounds geometry.Rect, fontSize float32, color Color, bold bool, align TextAlign)

	// MeasureText returns the width in pixels of the given text string
	// when rendered at the specified font size and weight.
	// This is essential for accurate cursor positioning in text fields.
	MeasureText(text string, fontSize float32, bold bool) float32

	// DrawImage draws an image at the specified position.
	//
	// The image is drawn with its top-left corner at the given point.
	// The image is composited using source-over blending. This method
	// is used by RepaintBoundary to blit cached subtree renders.
	DrawImage(img image.Image, at geometry.Point)

	// PushClip pushes a clipping rectangle onto the clip stack.
	//
	// All subsequent drawing operations will be clipped to this rectangle
	// intersected with any parent clip rectangles.
	PushClip(r geometry.Rect)

	// PushClipRoundRect pushes a rounded rectangle clipping region.
	//
	// All subsequent drawing operations will be clipped to this rounded
	// rectangle. Uses GPU SDF-based clipping when available (gg.ClipRoundRect).
	PushClipRoundRect(r geometry.Rect, radius float32)

	// PopClip removes the most recently pushed clipping region.
	//
	// Must be called for each PushClip or PushClipRoundRect call.
	PopClip()

	// PushTransform pushes a translation transform onto the transform stack.
	//
	// All subsequent drawing operations will be offset by the given point.
	PushTransform(offset geometry.Point)

	// PopTransform removes the most recently pushed transform.
	//
	// Must be called for each PushTransform call.
	PopTransform()

	// TransformOffset returns the current cumulative transform offset.
	//
	// This is the total translation applied by all PushTransform calls
	// currently on the transform stack. It represents the mapping from
	// local widget coordinates to window (screen) coordinates.
	//
	// Used by [StampScreenOrigin] to compute a widget's screen-space
	// position during the Draw pass.
	TransformOffset() geometry.Point
}

type Color struct {
	R, G, B, A float32
}

type Context interface {
	// RequestFocus requests focus for the given widget.
	//
	// If another widget currently has focus, it will receive a focus lost event.
	// The widget parameter should implement the Widget interface.
	RequestFocus(w Widget)

	// ReleaseFocus releases focus from the given widget.
	//
	// If the widget doesn't have focus, this is a no-op.
	// After calling this, FocusedWidget() will return nil.
	ReleaseFocus(w Widget)

	// IsFocused returns true if the given widget currently has focus.
	IsFocused(w Widget) bool

	// FocusedWidget returns the currently focused widget, or nil if none.
	FocusedWidget() Widget

	// Now returns the current time.
	//
	// This is the time at the start of the current frame/event cycle.
	// Use this for animations and time-based effects.
	Now() time.Time

	// DeltaTime returns the time elapsed since the previous frame.
	//
	// This is useful for smooth animations that should be frame-rate independent.
	// Returns 0 for the first frame.
	DeltaTime() time.Duration

	// Invalidate marks the entire window as needing a redraw.
	//
	// Call this when widget state changes require visual updates.
	// Multiple calls per frame are coalesced into a single redraw.
	Invalidate()

	// InvalidateRect marks a specific rectangular area as needing a redraw.
	//
	// Use this for more efficient partial redraws when only a small
	// part of the UI has changed.
	InvalidateRect(r geometry.Rect)

	// Cursor returns the current cursor type.
	Cursor() CursorType

	// SetCursor changes the mouse cursor.
	//
	// The cursor is typically reset to CursorDefault at the start of each frame.
	SetCursor(cursor CursorType)

	// Scale returns the display scale factor (DPI scaling).
	//
	// Returns 1.0 for standard displays, 2.0 for Retina/HiDPI displays, etc.
	// Use this to scale coordinates and sizes for proper rendering.
	Scale() float32

	// ThemeProvider returns the current theme for this context.
	//
	// Returns nil if no theme is set (headless mode without a theme).
	// Widgets should check for nil before using the returned provider.
	ThemeProvider() ThemeProvider

	// OverlayManager returns the overlay manager for pushing/removing overlays.
	//
	// Returns nil if no overlay manager is set (headless mode without a window).
	// Widgets should check for nil before calling overlay methods.
	OverlayManager() OverlayManager

	// WindowSize returns the current window size in logical pixels.
	WindowSize() geometry.Size

	// Scheduler returns the signal scheduler for this context.
	//
	// Returns nil if no scheduler is set (headless mode without signal support).
	// Widgets should check for nil before using the returned scheduler.
	Scheduler() SchedulerRef
}

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

type CursorType uint8

type DrawFunc func(ctx Context, canvas Canvas)

type DrawStats struct {
	// TotalWidgets is the total number of widgets visited during traversal.
	TotalWidgets int

	// DrawnWidgets is the number of widgets that had their Draw called.
	DrawnWidgets int

	// SkippedWidgets is the number of widgets skipped (invisible or nil).
	SkippedWidgets int

	// DirtyWidgets is the number of widgets that had their needsRedraw flag set.
	// In Sub-Phase 1 this equals DrawnWidgets for visible widgets.
	// In Sub-Phase 2 with pixel caching, clean widgets will be composited
	// from cache instead of re-drawn, so DirtyWidgets < DrawnWidgets.
	DirtyWidgets int

	// CleanWidgets is the number of visible widgets that did NOT have
	// their needsRedraw flag set. These are candidates for pixel caching
	// in Sub-Phase 2.
	CleanWidgets int

	// CachedWidgets is the number of RepaintBoundary widgets that served
	// their content from a cached pixmap instead of re-rendering the
	// child subtree. This is the primary metric for Sub-Phase 2 pixel
	// caching effectiveness.
	CachedWidgets int
}

type EventFunc func(ctx Context, e event.Event) bool

type Focusable interface {
	// IsFocusable reports whether this widget can currently receive focus.
	//
	// A widget may return false if it is disabled, invisible, or otherwise
	// unable to accept keyboard input at this time.
	IsFocusable() bool

	// SetFocused sets the widget's focus state.
	//
	// The focus manager calls this when focus is granted or revoked.
	// Widgets should update their visual appearance accordingly.
	SetFocused(focused bool)

	// IsFocused reports whether this widget currently has keyboard focus.
	IsFocused() bool
}

type LayoutFunc func(ctx Context, constraints geometry.Constraints) geometry.Size

type Lifecycle interface {
	// Mount is called when the widget is added to the tree.
	// Implementations should create signal bindings here via AddBinding().
	Mount(ctx Context)

	// Unmount is called when the widget is removed from the tree.
	// Implementations should clean up any resources not managed by AddBinding().
	// WidgetBase.CleanupBindings() is called automatically before Unmount().
	Unmount()
}

type OverlayManager interface {
	// PushOverlay pushes a widget as an overlay. The onDismiss callback is
	// called when the overlay should be closed (e.g. click outside, Escape key).
	PushOverlay(w Widget, onDismiss func())

	// PopOverlay removes the topmost overlay from the stack.
	PopOverlay()

	// RemoveOverlay removes a specific overlay widget from the stack.
	RemoveOverlay(w Widget)
}

type SchedulerRef interface {
	MarkDirty(w Widget)
}

type Stopper interface {
	Stop()
}

type TextAlign uint8

type ThemeProvider interface {
	// IsDark returns true if this is a dark theme.
	IsDark() bool

	// OnSurface returns the default color for text and icons on surface
	// backgrounds. Every design system (Material 3, Fluent, Cupertino)
	// defines an equivalent concept, making this a universal token.
	OnSurface() Color
}

type Unbinder interface {
	Unbind()
}

type Widget interface {
	// Layout calculates the widget's size given constraints from the parent.
	//
	// The constraints define the minimum and maximum allowed dimensions.
	// The returned size must satisfy the constraints (within min/max bounds).
	//
	// Layout is called during the layout phase, before Draw. The widget
	// should calculate its preferred size and return it constrained to
	// the allowed range.
	//
	// For container widgets, Layout should:
	//  1. Layout all children with appropriate constraints
	//  2. Position children by setting their bounds
	//  3. Return the container's total size
	//
	// Example:
	//
	//	func (w *MyWidget) Layout(ctx Context, c geometry.Constraints) geometry.Size {
	//	    preferred := geometry.Sz(100, 50)
	//	    return c.Constrain(preferred)
	//	}
	Layout(ctx Context, constraints geometry.Constraints) geometry.Size

	// Draw renders the widget to the canvas.
	//
	// Draw is called after Layout, when the widget's bounds are established.
	// The canvas provides drawing operations for rendering the widget.
	//
	// For container widgets, Draw should:
	//  1. Draw the container's own content (background, border, etc.)
	//  2. Draw all visible children
	//
	// Example:
	//
	//	func (w *MyWidget) Draw(ctx Context, canvas Canvas) {
	//	    canvas.DrawRect(w.Bounds(), w.backgroundColor)
	//	    for _, child := range w.Children() {
	//	        child.Draw(ctx, canvas)
	//	    }
	//	}
	Draw(ctx Context, canvas Canvas)

	// Event handles an input event and returns true if consumed.
	//
	// Events are dispatched from the root widget down through the tree.
	// A widget that handles an event should return true to prevent
	// further propagation.
	//
	// For container widgets, Event should:
	//  1. Check if event is within bounds
	//  2. Dispatch to appropriate child widgets
	//  3. Handle the event if no child consumed it
	//
	// Example:
	//
	//	func (w *MyWidget) Event(ctx Context, e event.Event) bool {
	//	    if me, ok := e.(*event.MouseEvent); ok {
	//	        if !w.Bounds().Contains(me.Position) {
	//	            return false
	//	        }
	//	        if me.MouseType == event.MousePress {
	//	            w.onClick()
	//	            return true
	//	        }
	//	    }
	//	    return false
	//	}
	Event(ctx Context, e event.Event) bool

	// Children returns the widget's child widgets.
	//
	// Leaf widgets (like labels, buttons) return nil.
	// Container widgets return their children in z-order (bottom to top).
	//
	// The returned slice should not be modified by the caller.
	Children() []Widget
}

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