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 // OnLinkHover is called when hovering over a link, image, or media element.
93 // The uri parameter contains the target URL, or empty string when leaving.
94 OnLinkHover func(uri string)
95}
96
97// FindOptions configures search behavior.
98type FindOptions struct {
99 CaseInsensitive bool
100 AtWordStarts bool
101 WrapAround bool
102}
103
104// FindController abstracts WebKit's FindController for clean architecture.
105type FindController interface {
106 Search(text string, options FindOptions, maxMatches uint)
107 CountMatches(text string, options FindOptions, maxMatches uint)
108 SearchNext()
109 SearchPrevious()
110 SearchFinish()
111 GetSearchText() string
112
113 // Signal connections
114 OnFoundText(callback func(matchCount uint)) uint32
115 OnFailedToFindText(callback func()) uint32
116 OnCountedMatches(callback func(matchCount uint)) uint32
117 DisconnectSignal(id uint32)
118}
119
120// WebView defines the port interface for browser view operations.
121// This interface abstracts the underlying browser engine (WebKit, etc.)
122// and exposes only the navigation and state capabilities needed by
123// the application layer.
124type WebView interface {
125 // ID returns the unique identifier for this WebView.
126 ID() WebViewID
127
128 // --- Navigation ---
129
130 // LoadURI navigates to the specified URI.
131 LoadURI(ctx context.Context, uri string) error
132
133 // LoadHTML loads HTML content with an optional base URI for relative links.
134 LoadHTML(ctx context.Context, content, baseURI string) error
135
136 // Reload reloads the current page.
137 Reload(ctx context.Context) error
138
139 // ReloadBypassCache reloads the current page, bypassing cache.
140 ReloadBypassCache(ctx context.Context) error
141
142 // Stop stops the current page load.
143 Stop(ctx context.Context) error
144
145 // GoBack navigates back in history.
146 // Returns error if back navigation is not possible.
147 GoBack(ctx context.Context) error
148
149 // GoForward navigates forward in history.
150 // Returns error if forward navigation is not possible.
151 GoForward(ctx context.Context) error
152
153 // --- State Queries ---
154
155 // State returns the current WebView state as a snapshot.
156 State() WebViewState
157
158 // URI returns the current URI.
159 URI() string
160
161 // Title returns the current page title.
162 Title() string
163
164 // IsLoading returns true if a page is currently loading.
165 IsLoading() bool
166
167 // EstimatedProgress returns the load progress (0.0 to 1.0).
168 EstimatedProgress() float64
169
170 // CanGoBack returns true if back navigation is available.
171 CanGoBack() bool
172
173 // CanGoForward returns true if forward navigation is available.
174 CanGoForward() bool
175
176 // --- Zoom ---
177
178 // SetZoomLevel sets the zoom level (1.0 = 100%).
179 SetZoomLevel(ctx context.Context, level float64) error
180
181 // GetZoomLevel returns the current zoom level.
182 GetZoomLevel() float64
183
184 // --- Find ---
185
186 // GetFindController returns the find controller for text search.
187 // Returns nil if find is not supported.
188 GetFindController() FindController
189
190 // --- Callbacks ---
191
192 // SetCallbacks registers callback handlers for WebView events.
193 // Pass nil to clear all callbacks.
194 SetCallbacks(callbacks *WebViewCallbacks)
195
196 // --- Media/Fullscreen State ---
197
198 // IsFullscreen returns true if the WebView is currently in fullscreen mode.
199 IsFullscreen() bool
200
201 // IsPlayingAudio returns true if the WebView is currently playing audio.
202 IsPlayingAudio() bool
203
204 // --- Lifecycle ---
205
206 // IsDestroyed returns true if the WebView has been destroyed.
207 IsDestroyed() bool
208
209 // Destroy releases all resources associated with this WebView.
210 // After calling Destroy, the WebView should not be used.
211 Destroy()
212}
213
214// WebViewPool defines the port interface for WebView pooling.
215// Pools maintain pre-created WebViews for fast tab creation.
216type WebViewPool interface {
217 // Acquire obtains a WebView from the pool or creates a new one.
218 // The context can be used for cancellation.
219 Acquire(ctx context.Context) (WebView, error)
220
221 // Release returns a WebView to the pool for reuse.
222 // The WebView will be reset to a blank state.
223 // If the pool is full, the WebView will be destroyed.
224 Release(wv WebView)
225
226 // Prewarm creates WebViews in the background to populate the pool.
227 // Pass count <= 0 to use the default prewarm count.
228 Prewarm(count int)
229
230 // Size returns the current number of available WebViews in the pool.
231 Size() int
232
233 // Close shuts down the pool and destroys all pooled WebViews.
234 Close()
235}
236
237// WebViewFactory creates new WebView instances.
238// This is used when direct WebView creation is needed without pooling.
239type WebViewFactory interface {
240 // Create creates a new WebView instance.
241 Create(ctx context.Context) (WebView, error)
242
243 // CreateRelated creates a WebView that shares session/cookies with parent.
244 // This is required for popup windows to maintain authentication state.
245 // Popup WebViews bypass the pool since they must be related to a specific parent.
246 CreateRelated(ctx context.Context, parentID WebViewID) (WebView, error)
247}