Skip to content

Commit d0635dc

Browse files
noisysockscursoragent
noisysocks
and
cursoragent
authored
Update special pages documentation examples and add new docs (#2079)
* Remove unused defaultStyles from initialSetupResponse Co-authored-by: randerson <[email protected]> * Add theme and themeVariant to history config and subscriptions Co-authored-by: randerson <[email protected]> * Add special error page documentation Co-authored-by: randerson <[email protected]> * Add error page documentation and include in typedoc Co-authored-by: randerson <[email protected]> --------- Co-authored-by: Cursor Agent <[email protected]>
1 parent 8658d25 commit d0635dc

File tree

5 files changed

+225
-12
lines changed

5 files changed

+225
-12
lines changed

‎special-pages/pages/errorpage/app/errorpage.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Error Page
3+
---
4+
5+
# Error Page
6+
7+
A simple error page template for browser loading failures. Unlike other special pages, this page does not use messaging—native interacts via string interpolation and a global callback.
8+
9+
## String Interpolation
10+
11+
Native performs string replacement on the HTML before loading:
12+
13+
| Variable | Description |
14+
|----------|-------------|
15+
| `$HEADER$` | Error title text |
16+
| `$ERROR_DESCRIPTION$` | Error description text |
17+
| `$THEME_VARIANT$` | Theme variant name (falls back to default if not replaced) |
18+
19+
## Runtime Theme Updates
20+
21+
Native can update the theme by calling:
22+
23+
```javascript
24+
window.onChangeTheme({ themeVariant: 'coolGray' });
25+
```
26+
27+
**Payload:**
28+
```json
29+
{
30+
"themeVariant": "violet"
31+
}
32+
```
33+
34+
Available theme variants: `default`, `coolGray`, `slateBlue`, `green`, `violet`, `rose`, `orange`, `desert`

‎special-pages/pages/history/app/history.md‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,13 @@ Configure initial history system settings.
2020
"env": "production",
2121
"platform": {
2222
"name": "macos"
23-
}
23+
},
24+
"theme": "light",
25+
"themeVariant": "default"
2426
}
2527
```
2628

27-
With {@link "History Messages".DefaultStyles} overrides
29+
With a different theme variant:
2830

2931
```json
3032
{
@@ -33,15 +35,13 @@ With {@link "History Messages".DefaultStyles} overrides
3335
"platform": {
3436
"name": "macos"
3537
},
36-
"customizer": {
37-
"defaultStyles": {
38-
"lightBackgroundColor": "#E9EBEC",
39-
"darkBackgroundColor": "#27282A"
40-
}
41-
}
38+
"theme": "dark",
39+
"themeVariant": "violet"
4240
}
4341
```
4442

43+
Available theme variants: `default`, `coolGray`, `slateBlue`, `green`, `violet`, `rose`, `orange`, `desert`
44+
4545
### `getRanges`
4646
{@link "History Messages".GetRangesRequest}
4747

@@ -268,6 +268,27 @@ still reply with an {@link "History Messages".ActionResponse} when the action wa
268268
If multiple `id`s are sent, then present a modal window for confirmation, eventually
269269
responding to the message with {@link "History Messages".ActionResponse}
270270

271+
## Subscriptions
272+
273+
### `onThemeUpdate`
274+
- {@link "History Messages".OnThemeUpdateSubscription}
275+
- Sends {@link "History Messages".OnThemeUpdateSubscribe} whenever the browser theme changes.
276+
- For example:
277+
```json
278+
{
279+
"theme": "dark",
280+
"themeVariant": "default"
281+
}
282+
```
283+
- Or, with a different theme variant:
284+
```json
285+
{
286+
"theme": "light",
287+
"themeVariant": "violet"
288+
}
289+
```
290+
- Available theme variants: `default`, `coolGray`, `slateBlue`, `green`, `violet`, `rose`, `orange`, `desert`
291+
271292
## Notifications
272293

273294
### `open`

‎special-pages/pages/new-tab/messages/examples/widgets.js‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,6 @@ const initialSetupResponse = {
5454
userImages: [],
5555
userColor: null,
5656
background: { kind: 'default' },
57-
defaultStyles: {
58-
lightBackgroundColor: '#E9EBEC',
59-
darkBackgroundColor: '#27282A',
60-
},
6157
},
6258
};
6359

‎special-pages/pages/special-error/app/special-error.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: Special Error Page
3+
---
4+
5+
# Special Error Page
6+
7+
Displays SSL certificate errors and malicious site warnings.
8+
9+
## Requests
10+
11+
### `initialSetup`
12+
{@link "SpecialError Messages".InitialSetupRequest}
13+
14+
Configure initial special error page settings.
15+
16+
**Types:**
17+
- Response: {@link "SpecialError Messages".InitialSetupResponse}
18+
19+
Example for a phishing warning:
20+
21+
```json
22+
{
23+
"locale": "en",
24+
"env": "production",
25+
"platform": {
26+
"name": "macos"
27+
},
28+
"errorData": {
29+
"kind": "phishing",
30+
"url": "https://malicious-example.com"
31+
},
32+
"theme": "light",
33+
"themeVariant": "default"
34+
}
35+
```
36+
37+
Example for a malware warning:
38+
39+
```json
40+
{
41+
"locale": "en",
42+
"env": "production",
43+
"platform": {
44+
"name": "windows"
45+
},
46+
"errorData": {
47+
"kind": "malware",
48+
"url": "https://malware-example.com"
49+
},
50+
"theme": "dark",
51+
"themeVariant": "default"
52+
}
53+
```
54+
55+
Example for an SSL expired certificate error:
56+
57+
```json
58+
{
59+
"locale": "en",
60+
"env": "production",
61+
"platform": {
62+
"name": "macos"
63+
},
64+
"errorData": {
65+
"kind": "ssl",
66+
"errorType": "expired",
67+
"domain": "expired.badssl.com"
68+
},
69+
"theme": "light",
70+
"themeVariant": "default"
71+
}
72+
```
73+
74+
Example for an SSL wrong host error:
75+
76+
```json
77+
{
78+
"locale": "en",
79+
"env": "production",
80+
"platform": {
81+
"name": "macos"
82+
},
83+
"errorData": {
84+
"kind": "ssl",
85+
"errorType": "wrongHost",
86+
"domain": "wrong.host.badssl.com",
87+
"eTldPlus1": "badssl.com"
88+
},
89+
"theme": "light",
90+
"themeVariant": "default"
91+
}
92+
```
93+
94+
### Error Data Types
95+
96+
**Malicious Site** (`kind`: `phishing` | `malware` | `scam`):
97+
- `kind`: Type of malicious site
98+
- `url`: The URL of the malicious site
99+
100+
**SSL Errors** (`kind`: `ssl`):
101+
- `errorType`: One of `expired`, `invalid`, `selfSigned`, `wrongHost`
102+
- `domain`: The domain with the certificate issue
103+
- `eTldPlus1`: (Only for `wrongHost`) The eTLD+1 of the expected domain
104+
105+
Available theme variants: `default`, `coolGray`, `slateBlue`, `green`, `violet`, `rose`, `orange`, `desert`
106+
107+
## Subscriptions
108+
109+
### `onThemeUpdate`
110+
- {@link "SpecialError Messages".OnThemeUpdateSubscription}
111+
- Sends {@link "SpecialError Messages".OnThemeUpdateSubscribe} whenever the browser theme changes.
112+
- For example:
113+
```json
114+
{
115+
"theme": "dark",
116+
"themeVariant": "default"
117+
}
118+
```
119+
- Or, with a different theme variant:
120+
```json
121+
{
122+
"theme": "light",
123+
"themeVariant": "violet"
124+
}
125+
```
126+
- Available theme variants: `default`, `coolGray`, `slateBlue`, `green`, `violet`, `rose`, `orange`, `desert`
127+
128+
## Notifications
129+
130+
### `leaveSite`
131+
- {@link "SpecialError Messages".LeaveSiteNotification}
132+
- Sent when the user clicks the "Leave Site" or "Go Back" button to navigate away from the dangerous site.
133+
134+
### `visitSite`
135+
- {@link "SpecialError Messages".VisitSiteNotification}
136+
- Sent when the user chooses to proceed to the site despite the warning.
137+
138+
### `advancedInfo`
139+
- {@link "SpecialError Messages".AdvancedInfoNotification}
140+
- Sent when the user clicks the "Advanced" button to view more details about the error.
141+
142+
### `reportInitException`
143+
- {@link "SpecialError Messages".ReportInitExceptionNotification}
144+
- Reports errors during page initialization.
145+
146+
```json
147+
{
148+
"message": "Failed to initialize special error page"
149+
}
150+
```
151+
152+
### `reportPageException`
153+
- {@link "SpecialError Messages".ReportPageExceptionNotification}
154+
- Reports errors during page operations.
155+
156+
```json
157+
{
158+
"message": "Failed to render error details"
159+
}
160+
```

‎typedoc.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ const config = {
66
projectDocuments: [
77
'special-pages/pages/new-tab/app/new-tab.md',
88
'special-pages/pages/history/app/history.md',
9+
'special-pages/pages/special-error/app/special-error.md',
10+
'special-pages/pages/errorpage/app/errorpage.md',
911
'injected/docs/*.md',
1012
'messaging/docs/messaging.md',
1113

0 commit comments

Comments
 (0)