browser-controls-api.yaml RawHistoryFolder
1openapi: 3.0.3
2info:
3 title: Browser Controls API
4 description: Wails backend API for browser keyboard and mouse controls
5 version: 0.1.0
6
7paths:
8 /zoom/in:
9 post:
10 summary: Zoom in to next higher level
11 description: Increases zoom level to next Firefox standard zoom level (FR-001)
12 requestBody:
13 required: true
14 content:
15 application/json:
16 schema:
17 type: object
18 properties:
19 domain:
20 type: string
21 description: Current website domain for persistence
22 example: "github.com"
23 required:
24 - domain
25 responses:
26 '200':
27 description: Zoom level successfully increased
28 content:
29 application/json:
30 schema:
31 $ref: '#/components/schemas/ZoomResponse'
32 '400':
33 description: Invalid domain or already at maximum zoom
34 content:
35 application/json:
36 schema:
37 $ref: '#/components/schemas/ErrorResponse'
38
39 /zoom/out:
40 post:
41 summary: Zoom out to next lower level
42 description: Decreases zoom level to next Firefox standard zoom level (FR-002)
43 requestBody:
44 required: true
45 content:
46 application/json:
47 schema:
48 type: object
49 properties:
50 domain:
51 type: string
52 description: Current website domain for persistence
53 example: "stackoverflow.com"
54 required:
55 - domain
56 responses:
57 '200':
58 description: Zoom level successfully decreased
59 content:
60 application/json:
61 schema:
62 $ref: '#/components/schemas/ZoomResponse'
63 '400':
64 description: Invalid domain or already at minimum zoom
65 content:
66 application/json:
67 schema:
68 $ref: '#/components/schemas/ErrorResponse'
69
70 /navigation/back:
71 post:
72 summary: Navigate to previous page in history
73 description: Navigates to previous page if history exists (FR-003, FR-010)
74 responses:
75 '200':
76 description: Successfully navigated back
77 content:
78 application/json:
79 schema:
80 $ref: '#/components/schemas/NavigationResponse'
81 '204':
82 description: No history available, no action taken
83 '500':
84 description: Navigation error
85 content:
86 application/json:
87 schema:
88 $ref: '#/components/schemas/ErrorResponse'
89
90 /navigation/forward:
91 post:
92 summary: Navigate to next page in history
93 description: Navigates to next page if forward history exists (FR-004, FR-010)
94 responses:
95 '200':
96 description: Successfully navigated forward
97 content:
98 application/json:
99 schema:
100 $ref: '#/components/schemas/NavigationResponse'
101 '204':
102 description: No forward history available, no action taken
103 '500':
104 description: Navigation error
105 content:
106 application/json:
107 schema:
108 $ref: '#/components/schemas/ErrorResponse'
109
110 /clipboard/copy-url:
111 post:
112 summary: Copy current URL to system clipboard
113 description: Copies current page URL using wlcopy/xclip/xsel fallback (FR-005, FR-006, FR-011)
114 requestBody:
115 required: true
116 content:
117 application/json:
118 schema:
119 type: object
120 properties:
121 url:
122 type: string
123 format: uri
124 description: Current page URL to copy
125 example: "https://github.com/bnema/dumber"
126 required:
127 - url
128 responses:
129 '200':
130 description: URL successfully copied to clipboard
131 content:
132 application/json:
133 schema:
134 type: object
135 properties:
136 success:
137 type: boolean
138 example: true
139 tool_used:
140 type: string
141 enum: ["wlcopy", "xclip", "xsel"]
142 example: "wlcopy"
143 message:
144 type: string
145 example: "URL copied to clipboard using wlcopy"
146 '500':
147 description: All clipboard tools failed
148 content:
149 application/json:
150 schema:
151 $ref: '#/components/schemas/ErrorResponse'
152
153 /zoom/get-level:
154 get:
155 summary: Get current zoom level for domain
156 description: Retrieves persisted zoom level for specific domain (FR-009)
157 parameters:
158 - name: domain
159 in: query
160 required: true
161 schema:
162 type: string
163 description: Website domain to query
164 example: "reddit.com"
165 responses:
166 '200':
167 description: Zoom level retrieved
168 content:
169 application/json:
170 schema:
171 $ref: '#/components/schemas/ZoomResponse'
172 '404':
173 description: No zoom level stored for domain (defaults to 100%)
174 content:
175 application/json:
176 schema:
177 $ref: '#/components/schemas/ZoomResponse'
178
179components:
180 schemas:
181 ZoomResponse:
182 type: object
183 properties:
184 zoom_factor:
185 type: number
186 format: float
187 description: Current zoom level as decimal (1.0 = 100%)
188 minimum: 0.3
189 maximum: 5.0
190 example: 1.2
191 zoom_percentage:
192 type: integer
193 description: Zoom level as percentage for UI display
194 minimum: 30
195 maximum: 500
196 example: 120
197 is_firefox_level:
198 type: boolean
199 description: Whether zoom level matches Firefox standard levels
200 example: true
201 domain:
202 type: string
203 description: Domain this zoom level applies to
204 example: "github.com"
205
206 NavigationResponse:
207 type: object
208 properties:
209 url:
210 type: string
211 format: uri
212 description: Target URL to navigate to
213 example: "https://previous-page.com"
214 title:
215 type: string
216 description: Page title if available
217 example: "Previous Page Title"
218 history_index:
219 type: integer
220 description: New position in history after navigation
221 example: 2
222 can_go_back:
223 type: boolean
224 description: Whether back navigation is still available
225 example: true
226 can_go_forward:
227 type: boolean
228 description: Whether forward navigation is available
229 example: false
230
231 ErrorResponse:
232 type: object
233 properties:
234 error:
235 type: string
236 description: Human-readable error message
237 example: "Already at maximum zoom level"
238 error_code:
239 type: string
240 description: Machine-readable error identifier
241 example: "MAX_ZOOM_REACHED"
242 timestamp:
243 type: string
244 format: date-time
245 description: Error occurrence timestamp
246 example: "2025-09-09T10:30:00Z"
247
248# Wails Service Methods (Go Implementation)
249# These correspond to the HTTP API but are called directly via Wails context:
250#
251# type BrowserControlService struct{}
252#
253# func (s *BrowserControlService) ZoomIn(ctx context.Context, domain string) (*ZoomResponse, error)
254# func (s *BrowserControlService) ZoomOut(ctx context.Context, domain string) (*ZoomResponse, error)
255# func (s *BrowserControlService) NavigateBack(ctx context.Context) (*NavigationResponse, error)
256# func (s *BrowserControlService) NavigateForward(ctx context.Context) (*NavigationResponse, error)
257# func (s *BrowserControlService) CopyCurrentURL(ctx context.Context, url string) (*ClipboardResponse, error)
258# func (s *BrowserControlService) GetZoomLevel(ctx context.Context, domain string) (*ZoomResponse, error)