webview.go RawHistoryFolder
1// Package port defines application-layer interfaces for external capabilities.
2// Ports abstract infrastructure concerns, allowing the application layer to
3// remain independent of specific implementations (WebKit, GTK, etc.).
4package port
5
6import (
7 "context"
8)
9
10// WebViewID uniquely identifies a WebView instance.
11type WebViewID uint64
12
13// LoadEvent represents page load state transitions.
14type LoadEvent int
15
16const (
17 // LoadStarted indicates navigation has begun.
18 LoadStarted LoadEvent = iota
19 // LoadRedirected indicates a redirect occurred.
20 LoadRedirected
21 // LoadCommitted indicates content is being received.
22 LoadCommitted
23 // LoadFinished indicates the page has fully loaded.
24 LoadFinished
25)
26
27// String returns a human-readable representation of the load event.
28func (e LoadEvent) String() string {
29 switch e {
30 case LoadStarted:
31 return "started"
32 case LoadRedirected:
33 return "redirected"
34 case LoadCommitted:
35 return "committed"
36 case LoadFinished:
37 return "finished"
38 default:
39 return "unknown"
40 }
41}
42
43// WebViewState represents a snapshot of the current WebView state.
44// This is an immutable struct that can be safely passed between components.
45type WebViewState struct {
46 URI string
47 Title string
48 IsLoading bool
49 Progress float64 // 0.0 to 1.0
50 CanGoBack bool
51 CanGoFwd bool
52 ZoomLevel float64
53}
54
55// PopupRequest contains metadata about a popup window request.
56type PopupRequest struct {
57 TargetURI string
58 FrameName string // e.g., "_blank", custom name, or empty
59 IsUserGesture bool
60 ParentViewID WebViewID
61}
62
63// Texture represents a graphics texture (abstraction over gdk.Texture).
64// This interface allows the port layer to work with textures without
65// importing GTK/GDK packages directly.
66type Texture interface {
67 // GoPointer returns the underlying C pointer for GTK interop.
68 GoPointer() uintptr
69}
70
71// WebViewCallbacks defines callback handlers for WebView events.
72// Implementations should invoke these on the main thread/goroutine.
73type WebViewCallbacks struct {
74 // OnLoadChanged is called when load state changes.
75 OnLoadChanged func(event LoadEvent)
76 // OnTitleChanged is called when the page title changes.
77 OnTitleChanged func(title string)
78 // OnURIChanged is called when the URI changes.
79 OnURIChanged func(uri string)
80 // OnProgressChanged is called during page load with progress 0.0-1.0.
81 OnProgressChanged func(progress float64)
82 // OnFaviconChanged is called when the page favicon changes.
83 // The parameter is a *gdk.Texture (passed as Texture interface to avoid GTK import in port layer).
84 OnFaviconChanged func(favicon Texture)
85 // OnClose is called when the WebView requests to close.
86 OnClose func()
87 // OnCreate is called when a popup window is requested.
88 // Return a WebView to allow the popup, or nil to block it.
89 OnCreate func(request PopupRequest) WebView
90 // OnReadyToShow is called when a popup WebView is ready to display.
91 OnReadyToShow func()
92}
93
94// FindOptions configures search behavior.
95type FindOptions struct {
96 CaseInsensitive bool
97 AtWordStarts bool
98 WrapAround bool
99}
100
101// FindController abstracts WebKit's FindController for clean architecture.
102type FindController interface {
103 Search(text string, options FindOptions, maxMatches uint)
104 CountMatches(text string, options FindOptions, maxMatches uint)
105 SearchNext()
106 SearchPrevious()
107 SearchFinish()
108 GetSearchText() string
109
110 // Signal connections
111 OnFoundText(callback func(matchCount uint)) uint32
112 OnFailedToFindText(callback func()) uint32
113 OnCountedMatches(callback func(matchCount uint)) uint32
114 DisconnectSignal(id uint32)
115}
116
117// WebView defines the port interface for browser view operations.
118// This interface abstracts the underlying browser engine (WebKit, etc.)
119// and exposes only the navigation and state capabilities needed by
120// the application layer.
121type WebView interface {
122 // ID returns the unique identifier for this WebView.
123 ID() WebViewID
124
125 // --- Navigation ---
126
127 // LoadURI navigates to the specified URI.
128 LoadURI(ctx context.Context, uri string) error
129
130 // LoadHTML loads HTML content with an optional base URI for relative links.
131 LoadHTML(ctx context.Context, content, baseURI string) error
132
133 // Reload reloads the current page.
134 Reload(ctx context.Context) error
135
136 // ReloadBypassCache reloads the current page, bypassing cache.
137 ReloadBypassCache(ctx context.Context) error
138
139 // Stop stops the current page load.
140 Stop(ctx context.Context) error
141
142 // GoBack navigates back in history.
143 // Returns error if back navigation is not possible.
144 GoBack(ctx context.Context) error
145
146 // GoForward navigates forward in history.
147 // Returns error if forward navigation is not possible.
148 GoForward(ctx context.Context) error
149
150 // --- State Queries ---
151
152 // State returns the current WebView state as a snapshot.
153 State() WebViewState
154
155 // URI returns the current URI.
156 URI() string
157
158 // Title returns the current page title.
159 Title() string
160
161 // IsLoading returns true if a page is currently loading.
162 IsLoading() bool
163
164 // EstimatedProgress returns the load progress (0.0 to 1.0).
165 EstimatedProgress() float64
166
167 // CanGoBack returns true if back navigation is available.
168 CanGoBack() bool
169
170 // CanGoForward returns true if forward navigation is available.
171 CanGoForward() bool
172
173 // --- Zoom ---
174
175 // SetZoomLevel sets the zoom level (1.0 = 100%).
176 SetZoomLevel(ctx context.Context, level float64) error
177
178 // GetZoomLevel returns the current zoom level.
179 GetZoomLevel() float64
180
181 // --- Find ---
182
183 // GetFindController returns the find controller for text search.
184 // Returns nil if find is not supported.
185 GetFindController() FindController
186
187 // --- Callbacks ---
188
189 // SetCallbacks registers callback handlers for WebView events.
190 // Pass nil to clear all callbacks.
191 SetCallbacks(callbacks *WebViewCallbacks)
192
193 // --- Lifecycle ---
194
195 // IsDestroyed returns true if the WebView has been destroyed.
196 IsDestroyed() bool
197
198 // Destroy releases all resources associated with this WebView.
199 // After calling Destroy, the WebView should not be used.
200 Destroy()
201}
202
203// WebViewPool defines the port interface for WebView pooling.
204// Pools maintain pre-created WebViews for fast tab creation.
205type WebViewPool interface {
206 // Acquire obtains a WebView from the pool or creates a new one.
207 // The context can be used for cancellation.
208 Acquire(ctx context.Context) (WebView, error)
209
210 // Release returns a WebView to the pool for reuse.
211 // The WebView will be reset to a blank state.
212 // If the pool is full, the WebView will be destroyed.
213 Release(wv WebView)
214
215 // Prewarm creates WebViews in the background to populate the pool.
216 // Pass count <= 0 to use the default prewarm count.
217 Prewarm(count int)
218
219 // Size returns the current number of available WebViews in the pool.
220 Size() int
221
222 // Close shuts down the pool and destroys all pooled WebViews.
223 Close()
224}
225
226// WebViewFactory creates new WebView instances.
227// This is used when direct WebView creation is needed without pooling.
228type WebViewFactory interface {
229 // Create creates a new WebView instance.
230 Create(ctx context.Context) (WebView, error)
231
232 // CreateRelated creates a WebView that shares session/cookies with parent.
233 // This is required for popup windows to maintain authentication state.
234 // Popup WebViews bypass the pool since they must be related to a specific parent.
235 CreateRelated(ctx context.Context, parentID WebViewID) (WebView, error)
236}