@glazeen/mod-sdk 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +221 -2
- package/bin/bearbar-mod.js +3 -0
- package/client/bb.css +58 -0
- package/client/bb.js +157 -0
- package/dist/bb-JW737zq0.d.ts +266 -0
- package/dist/cli.js +474 -0
- package/dist/global.d.ts +19 -0
- package/dist/global.js +0 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.js +284 -0
- package/docs/api.md +238 -0
- package/docs/guide.md +200 -0
- package/docs/manifest.md +198 -0
- package/docs/runtime.md +150 -0
- package/docs/styling.md +118 -0
- package/package.json +66 -3
- package/schema/bearbar.mod.schema.json +276 -0
package/docs/guide.md
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Writing a bearbar mod
|
|
2
|
+
|
|
3
|
+
A mod is a widget for the bearbar dock: a folder holding a manifest and one or two HTML pages.
|
|
4
|
+
It needs no build step and no package install. The dock serves the pages, injects the `bb`
|
|
5
|
+
runtime and a base stylesheet, and generates a settings popup from the manifest.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
my-mod/
|
|
9
|
+
bearbar.mod.json the manifest
|
|
10
|
+
tile.html the tile on the dock
|
|
11
|
+
panel.html optional popup, opened from the tile
|
|
12
|
+
anything.js/css/png/svg/woff2 ...
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Reference: [manifest](manifest.md) · [`bb` API](api.md) · [styling](styling.md) ·
|
|
16
|
+
[sandbox and runtime](runtime.md) · [CLI](../README.md#cli)
|
|
17
|
+
|
|
18
|
+
## 1. Create the mod
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npx @glazeen/mod-sdk init my-mod
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This writes `bearbar.mod.json`, `tile.html` and `tile.js` into `my-mod/` and never overwrites
|
|
25
|
+
existing files. You can also create the files by hand; the smallest mod is a manifest and a
|
|
26
|
+
page:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"$schema": "https://unpkg.com/@glazeen/mod-sdk/schema/bearbar.mod.schema.json",
|
|
31
|
+
"id": "my-mod",
|
|
32
|
+
"name": "My mod",
|
|
33
|
+
"version": "0.1.0",
|
|
34
|
+
"tile": "tile.html"
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```html
|
|
39
|
+
<!doctype html>
|
|
40
|
+
<html>
|
|
41
|
+
<body>
|
|
42
|
+
<div class="bb-tile"><span class="bb-value" id="v">…</span></div>
|
|
43
|
+
<script>
|
|
44
|
+
bb.ready.then(() => {
|
|
45
|
+
document.getElementById("v").textContent = "Hello";
|
|
46
|
+
});
|
|
47
|
+
</script>
|
|
48
|
+
</body>
|
|
49
|
+
</html>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The `$schema` line gives you validation and hover docs in VS Code and other JSON editors.
|
|
53
|
+
|
|
54
|
+
## 2. Install it
|
|
55
|
+
|
|
56
|
+
The mods folder is `%APPDATA%\bearbar\mods`. To open it, right-click the dock, choose
|
|
57
|
+
**Add widget…**, then click **Mods folder**. Copy your folder there, or link it so you can keep
|
|
58
|
+
it elsewhere:
|
|
59
|
+
|
|
60
|
+
```bat
|
|
61
|
+
mklink /J "%APPDATA%\bearbar\mods\my-mod" "C:\path\to\my-mod"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The mod appears in **Add widget → Mods** within a second. Add it to the dock from there.
|
|
65
|
+
|
|
66
|
+
Edits reload live: save any file in the mod and every tile of that mod reloads. If the mod
|
|
67
|
+
can't load (invalid JSON, a missing page, an invalid id), its tile shows the reason.
|
|
68
|
+
|
|
69
|
+
A mod in the user folder replaces a bundled mod with the same `id`. A mod can't replace a
|
|
70
|
+
built-in widget.
|
|
71
|
+
|
|
72
|
+
## 3. Wait for `bb.ready`
|
|
73
|
+
|
|
74
|
+
`bb` exists as soon as your script runs, but its state arrives from the dock a moment later.
|
|
75
|
+
Read `bb.config`, `bb.size` and `bb.surface` after `bb.ready` resolves:
|
|
76
|
+
|
|
77
|
+
```js
|
|
78
|
+
const { config, size } = await bb.ready;
|
|
79
|
+
render(config, size);
|
|
80
|
+
bb.on("config", (c) => render(c, bb.size));
|
|
81
|
+
bb.on("size", (s) => render(bb.config, s));
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
In a classic `<script>`, wrap this in an async function or use `bb.ready.then(...)`.
|
|
85
|
+
|
|
86
|
+
## 4. Add settings
|
|
87
|
+
|
|
88
|
+
Declare settings in the manifest. The dock generates the settings popup (right-click the tile >
|
|
89
|
+
Settings) and passes the values as `bb.config`, with defaults filled in:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
"settings": {
|
|
93
|
+
"city": { "type": "text", "label": "City", "placeholder": "Milan" },
|
|
94
|
+
"unit": {
|
|
95
|
+
"type": "select", "label": "Unit", "default": "c",
|
|
96
|
+
"options": [{ "value": "c", "label": "Celsius" }, { "value": "f", "label": "Fahrenheit" }]
|
|
97
|
+
},
|
|
98
|
+
"decimals": { "type": "number", "label": "Decimals", "default": 1, "min": 0, "max": 3 },
|
|
99
|
+
"showFeelsLike": { "type": "toggle", "label": "Show feels-like", "default": false }
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Settings without a `default` are missing from `bb.config` until the user sets them, so handle
|
|
104
|
+
`undefined`. See [setting fields](manifest.md#settings) for every option, including
|
|
105
|
+
`visibleWhen`.
|
|
106
|
+
|
|
107
|
+
## 5. Fetch data
|
|
108
|
+
|
|
109
|
+
Pages can't make network requests themselves: the sandbox blocks `fetch`, images from the web
|
|
110
|
+
and remote scripts. Declare each host as a permission and go through `bb.fetch`:
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
"permissions": ["net:api.example.com"]
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```js
|
|
117
|
+
const res = await bb.fetch(`https://api.example.com/weather?city=${encodeURIComponent(city)}`);
|
|
118
|
+
if (res.ok) render(res.json());
|
|
119
|
+
else showError(res.error ?? `HTTP ${res.status}`);
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`bb.fetch` never rejects for a failed request: check `res.ok`. Only https is allowed. See
|
|
123
|
+
[`bb.fetch`](api.md#bbfetchurl-init) for the limits.
|
|
124
|
+
|
|
125
|
+
## 6. Handle the widget picker
|
|
126
|
+
|
|
127
|
+
The widget picker shows a live preview of your tile. There, `bb.preview` is `true`, `bb.fetch`
|
|
128
|
+
always fails and storage writes are dropped. Show sample data instead of an error:
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
const data = bb.preview ? SAMPLE : await load();
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## 7. Remember things
|
|
135
|
+
|
|
136
|
+
`bb.storage` is a small key-value store per widget instance, kept with the dock's settings.
|
|
137
|
+
Use it to cache the last result so the tile shows something while it reloads:
|
|
138
|
+
|
|
139
|
+
```js
|
|
140
|
+
const last = await bb.storage.get("last");
|
|
141
|
+
if (last) render(last);
|
|
142
|
+
const fresh = await load();
|
|
143
|
+
await bb.storage.set("last", fresh);
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Values must be JSON. The whole store is limited to 256 KB. `localStorage`, `IndexedDB` and
|
|
147
|
+
cookies don't work in the sandbox.
|
|
148
|
+
|
|
149
|
+
## 8. Add a panel
|
|
150
|
+
|
|
151
|
+
A panel is a popup above the tile, for detail that doesn't fit. Declare it and open it from the
|
|
152
|
+
tile:
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
"panel": "panel.html",
|
|
156
|
+
"panelSize": { "width": 300, "height": 240 }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
```js
|
|
160
|
+
document.getElementById("open").addEventListener("click", () => bb.panel.open());
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
The panel page gets the same `bb`, with `bb.surface === "panel"`, the same config and the same
|
|
164
|
+
storage as its tile. `bb.panel.close()` closes it.
|
|
165
|
+
|
|
166
|
+
## 9. Style it
|
|
167
|
+
|
|
168
|
+
Your page inherits the dock's colours and fonts through CSS variables, and the base stylesheet
|
|
169
|
+
sets a transparent background, the dock font and helper classes like `bb-tile` and `bb-value`.
|
|
170
|
+
Style against `data-tone` to look right on light and dark surfaces. See [styling](styling.md).
|
|
171
|
+
|
|
172
|
+
## 10. Check it
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
npx @glazeen/mod-sdk validate my-mod
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
This checks the manifest, that the pages exist, and that they don't load anything remote. Add
|
|
179
|
+
`--strict` in CI to fail on warnings too.
|
|
180
|
+
|
|
181
|
+
## Debugging
|
|
182
|
+
|
|
183
|
+
- **The tile shows an error:** the manifest couldn't be loaded. Run `validate` for details.
|
|
184
|
+
- **"needs the … permission":** add the permission to `permissions` and save.
|
|
185
|
+
- **Nothing happens on right-click:** that's by design; the dock owns right-click and opens the
|
|
186
|
+
widget menu.
|
|
187
|
+
- **Console output and DevTools:** only development builds of bearbar have DevTools (run it
|
|
188
|
+
from source with `pnpm dev`, then right-click the dock > Open DevTools and choose the mod's
|
|
189
|
+
frame in the Console's JavaScript context dropdown). In a release build, show errors in the tile while
|
|
190
|
+
developing.
|
|
191
|
+
|
|
192
|
+
## Sharing a mod
|
|
193
|
+
|
|
194
|
+
Share the folder (for example as a zip or a git repository). Users copy it into their mods
|
|
195
|
+
folder. There is no mod store yet.
|
|
196
|
+
|
|
197
|
+
## Example
|
|
198
|
+
|
|
199
|
+
[`crypto-price`](https://github.com/glazeen/bearbar/tree/main/mods/crypto-price) ships with
|
|
200
|
+
bearbar: a tile and a panel, settings, storage, network and `open-url`.
|
package/docs/manifest.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# bearbar.mod.json reference
|
|
2
|
+
|
|
3
|
+
Every mod folder has a `bearbar.mod.json` at its root. It is plain JSON (a UTF-8 BOM is
|
|
4
|
+
allowed). The [JSON Schema](../schema/bearbar.mod.schema.json) describes it for editors, and
|
|
5
|
+
`bearbar-mod validate` checks it, including the rules the schema can't express.
|
|
6
|
+
|
|
7
|
+
```json
|
|
8
|
+
{
|
|
9
|
+
"$schema": "https://unpkg.com/@glazeen/mod-sdk/schema/bearbar.mod.schema.json",
|
|
10
|
+
"id": "weather-lite",
|
|
11
|
+
"name": "Weather lite",
|
|
12
|
+
"version": "1.0.0",
|
|
13
|
+
"apiVersion": 1,
|
|
14
|
+
"description": "Temperature for one city.",
|
|
15
|
+
"author": "you",
|
|
16
|
+
"sizes": { "s": 1, "m": 2 },
|
|
17
|
+
"tile": "tile.html",
|
|
18
|
+
"panel": "panel.html",
|
|
19
|
+
"panelSize": { "width": 300, "height": 240 },
|
|
20
|
+
"permissions": ["net:api.example.com", "open-url"],
|
|
21
|
+
"settings": {
|
|
22
|
+
"city": { "type": "text", "label": "City", "placeholder": "Milan" },
|
|
23
|
+
"unit": {
|
|
24
|
+
"type": "select",
|
|
25
|
+
"label": "Unit",
|
|
26
|
+
"default": "c",
|
|
27
|
+
"options": [
|
|
28
|
+
{ "value": "c", "label": "Celsius" },
|
|
29
|
+
{ "value": "f", "label": "Fahrenheit" }
|
|
30
|
+
]
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Fields
|
|
37
|
+
|
|
38
|
+
| Field | Type | Required | Notes |
|
|
39
|
+
| ------------- | -------- | -------- | ----------------------------------------------------------- |
|
|
40
|
+
| `$schema` | string | | Schema URL, for editors. Ignored by the dock. |
|
|
41
|
+
| `id` | string | yes | See [id](#id). |
|
|
42
|
+
| `name` | string | yes | Shown in the widget picker and as the frame title. |
|
|
43
|
+
| `version` | string | yes | Semantic version, like `"1.2.0"`. Shown in the picker. |
|
|
44
|
+
| `apiVersion` | integer | | Mod API version the mod targets. Missing means `1`. |
|
|
45
|
+
| `description` | string | | One line for the widget picker. |
|
|
46
|
+
| `author` | string | | Shown in the picker when there is no description. |
|
|
47
|
+
| `sizes` | object | | See [sizes](#sizes). Default `{ "m": 2 }`. |
|
|
48
|
+
| `tile` | string | yes | The tile page. See [pages](#tile-and-panel). |
|
|
49
|
+
| `panel` | string | | The popup page, opened with `bb.panel.open()`. |
|
|
50
|
+
| `panelSize` | object | | `{ "width", "height" }` in pixels. Default `320 × 360`. |
|
|
51
|
+
| `permissions` | string[] | | See [permissions](#permissions). |
|
|
52
|
+
| `settings` | object | | See [settings](#settings). |
|
|
53
|
+
| `category` | string | | Ignored: mods are always listed under Mods. |
|
|
54
|
+
|
|
55
|
+
Unknown top-level properties are a warning (with a suggestion when they look like a typo), so
|
|
56
|
+
a manifest written for a newer dock still loads.
|
|
57
|
+
|
|
58
|
+
### id
|
|
59
|
+
|
|
60
|
+
2 to 64 characters: letters, digits, `.`, `_` and `-`, starting with a letter or digit
|
|
61
|
+
(`MOD_ID_PATTERN`). Pick something unique, such as `yourname.weather`.
|
|
62
|
+
|
|
63
|
+
- The id names the widget in the user's saved dock layout. Changing it orphans every placed
|
|
64
|
+
tile of the mod.
|
|
65
|
+
- A mod in the user folder replaces a bundled mod with the same id.
|
|
66
|
+
- An id that matches a built-in widget's is ignored.
|
|
67
|
+
|
|
68
|
+
When the manifest has no valid id, the dock falls back to the folder name and shows an error
|
|
69
|
+
on the tile.
|
|
70
|
+
|
|
71
|
+
### sizes
|
|
72
|
+
|
|
73
|
+
The tile width in dock units for each size the mod supports. One unit is one square tile;
|
|
74
|
+
fractions are allowed.
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
"sizes": { "s": 1, "m": 2.5, "l": 4 }
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Keys are `s`, `m` and `l`; values are positive numbers.
|
|
81
|
+
- The user picks the size from the widget menu, among the sizes you list. New tiles start at
|
|
82
|
+
`m` if you list it, otherwise at the first listed size.
|
|
83
|
+
- Without `sizes`, the mod has one size, `m`, two units wide.
|
|
84
|
+
- The current size is `bb.size`, and `bb.on("size")` reports changes.
|
|
85
|
+
|
|
86
|
+
### tile and panel
|
|
87
|
+
|
|
88
|
+
Paths to `.html` files inside the mod folder, relative to it (`"tile.html"`,
|
|
89
|
+
`"pages/panel.html"`). Absolute paths, drive letters, URLs and `..` are rejected. The file
|
|
90
|
+
must exist, or the tile shows an error.
|
|
91
|
+
|
|
92
|
+
`panelSize` only matters when there is a `panel`.
|
|
93
|
+
|
|
94
|
+
### permissions
|
|
95
|
+
|
|
96
|
+
| Permission | What it allows |
|
|
97
|
+
| ------------------- | ----------------------------------------------------------------------- |
|
|
98
|
+
| `net:<host>` | `bb.fetch()` to that host, over https. |
|
|
99
|
+
| `net:*.example.com` | `bb.fetch()` to `example.com` and all its subdomains. |
|
|
100
|
+
| `open-url` | `bb.openUrl()` opens http(s) links in the default browser. |
|
|
101
|
+
| `system` | `bb.on("system")` receives CPU and RAM usage every 2 seconds. |
|
|
102
|
+
|
|
103
|
+
- Hosts are matched case-insensitively and without a port or path: `net:api.example.com`, not
|
|
104
|
+
`net:https://api.example.com/v1`.
|
|
105
|
+
- Only public host names: IP addresses (`net:127.0.0.1`), `localhost`, single-label names
|
|
106
|
+
(`net:intranet`) and `.local` / `.internal` / `.home.arpa` names are an error, and the dock
|
|
107
|
+
refuses them at runtime too. A wildcard must cover a domain: `net:*.example.com`, not
|
|
108
|
+
`net:*.com`.
|
|
109
|
+
- Duplicates are an error. Unknown permissions are an error for the validator; the dock ignores
|
|
110
|
+
them.
|
|
111
|
+
- Without a permission, the matching call fails: `bb.fetch` resolves with `ok: false`, the
|
|
112
|
+
others reject.
|
|
113
|
+
|
|
114
|
+
A manifest only asks for permissions. A mod the user installed needs the user's approval, in
|
|
115
|
+
Settings › Mods, before its permissions apply. Until every permission it declares is approved
|
|
116
|
+
the mod is blocked: the dock shows a placeholder instead of its tile and grants it nothing. A
|
|
117
|
+
mod that declares no permissions needs no approval. If an update asks for more than was
|
|
118
|
+
approved, the mod is blocked again until the user approves the new list; asking for less needs
|
|
119
|
+
nothing. Mods bundled with bearbar don't need approval.
|
|
120
|
+
|
|
121
|
+
There is no permission for file system, clipboard, notifications or other native access.
|
|
122
|
+
|
|
123
|
+
### settings
|
|
124
|
+
|
|
125
|
+
An object mapping each setting key to a field. The dock generates the settings popup from it,
|
|
126
|
+
in the order you declare the fields, and passes the values to the page as `bb.config`.
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
"settings": {
|
|
130
|
+
"city": { "type": "text", "label": "City", "placeholder": "Milan" },
|
|
131
|
+
"count": { "type": "number", "label": "Items", "default": 5, "min": 1, "max": 20 },
|
|
132
|
+
"compact": { "type": "toggle", "label": "Compact", "default": false },
|
|
133
|
+
"unit": { "type": "select", "label": "Unit", "default": "c",
|
|
134
|
+
"options": [{ "value": "c", "label": "Celsius" }, { "value": "f", "label": "Fahrenheit" }] }
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Every field has:
|
|
139
|
+
|
|
140
|
+
| Property | Type | Required | Notes |
|
|
141
|
+
| ------------- | ------ | -------- | -------------------------------------------------------- |
|
|
142
|
+
| `type` | string | yes | `text`, `number`, `toggle` or `select`. |
|
|
143
|
+
| `label` | string | yes | Shown next to the control. |
|
|
144
|
+
| `description` | string | | Help text under the control. |
|
|
145
|
+
| `visibleWhen` | object | | `{ "field", "equals" }`. See below. |
|
|
146
|
+
| `default` | varies | | The value until the user changes it. |
|
|
147
|
+
|
|
148
|
+
Per type:
|
|
149
|
+
|
|
150
|
+
| Type | Value in `bb.config` | Extra properties |
|
|
151
|
+
| -------- | -------------------- | ----------------------------------------------------- |
|
|
152
|
+
| `text` | string | `placeholder` (string) |
|
|
153
|
+
| `number` | number | `min`, `max`, `step` (numbers; `step` > 0) |
|
|
154
|
+
| `toggle` | boolean | |
|
|
155
|
+
| `select` | string | `options`: `[{ "value", "label" }]`, at least one |
|
|
156
|
+
|
|
157
|
+
Rules the validator enforces:
|
|
158
|
+
|
|
159
|
+
- Properties that don't belong to the field's type are errors (with a suggestion for typos).
|
|
160
|
+
- `default` must have the field's type. A select default must be one of the option values.
|
|
161
|
+
- Select option values must be unique, and options have only `value` and `label`.
|
|
162
|
+
- `min` can't be greater than `max`. A number default outside `min..max` is a warning.
|
|
163
|
+
|
|
164
|
+
**Defaults.** `bb.config` holds every field that has a `default`, overridden by what the user
|
|
165
|
+
set. A field without a default is missing from `bb.config` until the user sets it.
|
|
166
|
+
|
|
167
|
+
**visibleWhen.** Shows a field only while another setting has a given value. `field` must name
|
|
168
|
+
another setting in the same manifest; `equals` is a string, number or boolean compared with
|
|
169
|
+
`===`.
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
"source": { "type": "select", "label": "Source", "default": "auto",
|
|
173
|
+
"options": [{ "value": "auto", "label": "Automatic" }, { "value": "city", "label": "City" }] },
|
|
174
|
+
"city": { "type": "text", "label": "City", "visibleWhen": { "field": "source", "equals": "city" } }
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Hiding a field doesn't remove its value from `bb.config`.
|
|
178
|
+
|
|
179
|
+
**Typing settings in TypeScript.** `InferConfig<typeof manifest>` derives the `bb.config` type
|
|
180
|
+
from settings declared with `defineManifest`. See the
|
|
181
|
+
[package README](../README.md#typed-config).
|
|
182
|
+
|
|
183
|
+
## What the dock does with a broken manifest
|
|
184
|
+
|
|
185
|
+
The dock is lenient so a small mistake doesn't remove a widget from someone's dock:
|
|
186
|
+
|
|
187
|
+
- Invalid JSON: the mod is listed under its folder name, with the parse error on the tile.
|
|
188
|
+
- Missing `name`, `version` or `tile`: filled in from the id, `"0.0.0"` and `"tile.html"`.
|
|
189
|
+
- Invalid `id` or a missing page: the mod is listed with an error on the tile.
|
|
190
|
+
- Other mistakes (a bad setting, an unknown permission) are not checked when loading.
|
|
191
|
+
|
|
192
|
+
The validator is strict about all of these. Run it before you share a mod.
|
|
193
|
+
|
|
194
|
+
## Versioning
|
|
195
|
+
|
|
196
|
+
`version` is your mod's version; the dock shows it but doesn't compare it. `apiVersion` is the
|
|
197
|
+
version of the mod API you wrote against. See
|
|
198
|
+
[API versions](../README.md#api-versions).
|
package/docs/runtime.md
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Sandbox and runtime
|
|
2
|
+
|
|
3
|
+
How the dock loads and isolates mods, and the message protocol between a mod page and the
|
|
4
|
+
dock. Mod authors need the [sandbox rules](#the-sandbox); the [protocol](#the-protocol) matters
|
|
5
|
+
only if you work on the `bb` runtime or host mods in another app.
|
|
6
|
+
|
|
7
|
+
## Loading
|
|
8
|
+
|
|
9
|
+
- The dock scans two folders: the mods bundled with bearbar, and `%APPDATA%\bearbar\mods`.
|
|
10
|
+
Each subfolder with a `bearbar.mod.json` is a mod. A user mod replaces a bundled mod with the
|
|
11
|
+
same id.
|
|
12
|
+
- The user folder is watched. Any change rescans both folders after 300 ms and reloads the
|
|
13
|
+
mod pages on the dock.
|
|
14
|
+
- Pages are served from `bbmod://mods/<id>/<path>`. The dock adds the runtime to each HTML
|
|
15
|
+
page by inserting `<link rel="stylesheet" href="bbmod://mods/_sdk/sdk.css">` and
|
|
16
|
+
`<script src="bbmod://mods/_sdk/sdk.js">` right after `<head>` (or at the start of the
|
|
17
|
+
file when there is no `<head>`). So `bb` exists before your own scripts run.
|
|
18
|
+
- Files are served with `Cache-Control: no-cache`. Paths outside the mod folder get `403`.
|
|
19
|
+
|
|
20
|
+
Served file types:
|
|
21
|
+
|
|
22
|
+
| Extension | Content type |
|
|
23
|
+
| ------------------------------- | ------------------------ |
|
|
24
|
+
| `.html` | `text/html` |
|
|
25
|
+
| `.js`, `.mjs` | `text/javascript` |
|
|
26
|
+
| `.css` | `text/css` |
|
|
27
|
+
| `.json` | `application/json` |
|
|
28
|
+
| `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` | images |
|
|
29
|
+
| `.woff2`, `.woff` | fonts |
|
|
30
|
+
|
|
31
|
+
Any other extension gets `415 Unsupported Media Type`.
|
|
32
|
+
|
|
33
|
+
## The sandbox
|
|
34
|
+
|
|
35
|
+
Each page runs in an `<iframe sandbox="allow-scripts">`. That means:
|
|
36
|
+
|
|
37
|
+
- **Opaque origin.** No cookies, `localStorage`, `sessionStorage` or `IndexedDB` (they throw).
|
|
38
|
+
Use [`bb.storage`](api.md#bbstorage).
|
|
39
|
+
- **No navigation, popups, forms or dialogs.** Links don't open, `window.open` and form
|
|
40
|
+
submission do nothing, `alert`/`confirm`/`prompt` are blocked. Use
|
|
41
|
+
[`bb.openUrl`](api.md#bbopenurlurl) for links.
|
|
42
|
+
- **No access to the dock.** No Node, no Electron, no access to the dock's DOM or other mods.
|
|
43
|
+
|
|
44
|
+
Every response also carries this Content Security Policy:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
default-src 'none';
|
|
48
|
+
script-src bbmod: 'unsafe-inline';
|
|
49
|
+
style-src bbmod: 'unsafe-inline';
|
|
50
|
+
img-src bbmod: data:;
|
|
51
|
+
font-src bbmod: data:;
|
|
52
|
+
connect-src 'none';
|
|
53
|
+
frame-src 'none';
|
|
54
|
+
form-action 'none'
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- Inline and local scripts and styles work. Scripts and styles from the web don't: copy
|
|
58
|
+
libraries into the mod folder.
|
|
59
|
+
- `eval` and `new Function` are blocked, so libraries that compile code at runtime (some
|
|
60
|
+
template engines, some chart libraries' "unsafe" builds) won't work.
|
|
61
|
+
- `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` are blocked. All network traffic goes
|
|
62
|
+
through [`bb.fetch`](api.md#bbfetchurl-init).
|
|
63
|
+
- Images and fonts load from the mod folder or `data:` URLs only.
|
|
64
|
+
- Prefer classic `<script src>` tags. Module scripts aren't a supported setup.
|
|
65
|
+
|
|
66
|
+
**Right-click** belongs to the dock: the runtime cancels the page's context menu and asks the
|
|
67
|
+
dock to open the widget menu (Settings, Size, Remove) instead.
|
|
68
|
+
|
|
69
|
+
All mods share the `bbmod://mods` origin for serving, so however many mods are on the dock they
|
|
70
|
+
cost one extra renderer process together, not one each. Isolation between them comes from the
|
|
71
|
+
sandbox, not from separate origins. A mod's frame can only show pages from its own folder:
|
|
72
|
+
the dock refuses to navigate it to another mod or to the web.
|
|
73
|
+
|
|
74
|
+
## Permission checks
|
|
75
|
+
|
|
76
|
+
Permissions are checked by the dock, outside the page, against the manifest on disk and what
|
|
77
|
+
the user approved of it (a user mod waiting for approval gets none; see
|
|
78
|
+
[permissions](manifest.md#permissions)):
|
|
79
|
+
|
|
80
|
+
- `bb.fetch` runs in the main process. It requires `https:`, refuses IP addresses and local
|
|
81
|
+
names (`localhost`, `.local`...), matches the URL's host against the `net:` permissions,
|
|
82
|
+
sends no cookies or credentials, times out after 15 seconds and stops reading a response
|
|
83
|
+
past 2 MB. Each redirect is checked the same way before it is followed, up to 5.
|
|
84
|
+
- `bb.openUrl` checks `open-url`, only opens `http:` and `https:` URLs, and opens at most one
|
|
85
|
+
link every 2 seconds (5 a minute) per mod.
|
|
86
|
+
- `bb.storage` is saved by the dock, which refuses a store over `STORAGE_QUOTA` as well.
|
|
87
|
+
- The `system` subscription checks `system`.
|
|
88
|
+
|
|
89
|
+
The runtime in the page is a convenience: bypassing it gains nothing, since every privileged
|
|
90
|
+
action goes through these checks.
|
|
91
|
+
|
|
92
|
+
## The protocol
|
|
93
|
+
|
|
94
|
+
The runtime ([`client/bb.js`](../client/bb.js)) talks to the dock with `postMessage`. Every
|
|
95
|
+
message is a plain object with `bb: true`. The page posts to `parent` with target origin
|
|
96
|
+
`"*"` (its own origin is opaque); each side accepts messages only from the other window.
|
|
97
|
+
|
|
98
|
+
### Handshake
|
|
99
|
+
|
|
100
|
+
1. The runtime posts `{ bb: true, type: "hello" }` as soon as it loads.
|
|
101
|
+
2. The dock answers:
|
|
102
|
+
|
|
103
|
+
```js
|
|
104
|
+
{ bb: true, type: "init", size, config, preview, surface, theme }
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The runtime stores the state, applies the theme (CSS variables and `data-*` attributes on
|
|
108
|
+
`<html>`) and resolves `bb.ready`.
|
|
109
|
+
|
|
110
|
+
### Calls
|
|
111
|
+
|
|
112
|
+
The page sends `{ bb: true, type: "call", id, method, args }` with a numeric `id` that
|
|
113
|
+
increases per page. The dock answers `{ bb: true, type: "reply", id, ok: true, value }` or
|
|
114
|
+
`{ bb: true, type: "reply", id, ok: false, error }`, and the runtime resolves or rejects the
|
|
115
|
+
matching promise.
|
|
116
|
+
|
|
117
|
+
| `method` | `args` | `value` |
|
|
118
|
+
| ------------------ | ----------------------------------- | ------------------------------- |
|
|
119
|
+
| `fetch` | `[{ url, method?, headers?, body? }]` | `{ ok, status, text, error? }` |
|
|
120
|
+
| `storage.get` | `[key]` | the stored value |
|
|
121
|
+
| `storage.set` | `[key, value]` | `true` |
|
|
122
|
+
| `panel.open` | `[]` | `true` |
|
|
123
|
+
| `panel.close` | `[]` | `true` |
|
|
124
|
+
| `openUrl` | `[url]` | `true` |
|
|
125
|
+
| `settings.open` | `[]` | `true` |
|
|
126
|
+
| `system.subscribe` | `[]` | `true` |
|
|
127
|
+
|
|
128
|
+
`headers` is normalised to a plain object before sending. An unknown method fails with
|
|
129
|
+
`unknown method <name>`.
|
|
130
|
+
|
|
131
|
+
### Pushes from the dock
|
|
132
|
+
|
|
133
|
+
| `type` | Fields | Runtime effect |
|
|
134
|
+
| -------- | -------- | --------------------------------------------------- |
|
|
135
|
+
| `config` | `config` | Updates `bb.config`, emits `config`. |
|
|
136
|
+
| `size` | `size` | Updates `bb.size`, emits `size`. |
|
|
137
|
+
| `theme` | `theme` | Applies the theme, emits `theme`. |
|
|
138
|
+
| `system` | `stats` | Emits `system` (after `system.subscribe`). |
|
|
139
|
+
|
|
140
|
+
### From the page
|
|
141
|
+
|
|
142
|
+
| `type` | Meaning |
|
|
143
|
+
| ------------- | ------------------------------------------------------------- |
|
|
144
|
+
| `hello` | The runtime loaded; send `init`. |
|
|
145
|
+
| `call` | See [calls](#calls). |
|
|
146
|
+
| `contextmenu` | The user right-clicked; open the widget menu (tiles only). |
|
|
147
|
+
|
|
148
|
+
Changing the protocol in a way an older runtime or dock can't handle is a breaking change of
|
|
149
|
+
the mod API (see [API versions](../README.md#api-versions)). New methods, pushes and fields are
|
|
150
|
+
additive.
|
package/docs/styling.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Styling a mod
|
|
2
|
+
|
|
3
|
+
The dock gives every mod page its look through CSS variables and `data-*` attributes on
|
|
4
|
+
`<html>`, plus a small base stylesheet. Use them and your mod follows the user's theme,
|
|
5
|
+
material and accent colour without extra code.
|
|
6
|
+
|
|
7
|
+
## The base stylesheet
|
|
8
|
+
|
|
9
|
+
Injected before your own styles ([`client/bb.css`](../client/bb.css)). It:
|
|
10
|
+
|
|
11
|
+
- sets a transparent background, so the dock's material shows through,
|
|
12
|
+
- uses the dock's text colour, font and small font size,
|
|
13
|
+
- removes body margins and scrolling (`overflow: hidden`) and fills the frame,
|
|
14
|
+
- turns off text selection and sets `box-sizing: border-box` everywhere,
|
|
15
|
+
- makes buttons inherit the font and colour.
|
|
16
|
+
|
|
17
|
+
Override any of it in your own CSS.
|
|
18
|
+
|
|
19
|
+
## Helper classes
|
|
20
|
+
|
|
21
|
+
These match the built-in tiles:
|
|
22
|
+
|
|
23
|
+
| Class | Use |
|
|
24
|
+
| ---------- | --------------------------------------------------------------------- |
|
|
25
|
+
| `bb-tile` | Root of a tile: full height, centred row with padding. |
|
|
26
|
+
| `bb-stack` | A column of lines, tight line height. |
|
|
27
|
+
| `bb-label` | Small uppercase caption in the dim colour. |
|
|
28
|
+
| `bb-value` | Large display number, tabular figures. |
|
|
29
|
+
| `bb-dim` | Secondary text colour. |
|
|
30
|
+
| `bb-up` | Green, for rising values. |
|
|
31
|
+
| `bb-down` | Red, for falling values. |
|
|
32
|
+
|
|
33
|
+
```html
|
|
34
|
+
<div class="bb-tile">
|
|
35
|
+
<div class="bb-stack">
|
|
36
|
+
<span class="bb-label">BTC</span>
|
|
37
|
+
<span class="bb-value">64,250</span>
|
|
38
|
+
</div>
|
|
39
|
+
<span class="bb-up">+2.4%</span>
|
|
40
|
+
</div>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## CSS variables
|
|
44
|
+
|
|
45
|
+
| Variable | What |
|
|
46
|
+
| -------------------- | ------------------------------------------------------------- |
|
|
47
|
+
| `--bb-text` | Main text colour. |
|
|
48
|
+
| `--bb-text-dim` | Secondary text colour. |
|
|
49
|
+
| `--bb-accent` | The user's accent colour, for fills. |
|
|
50
|
+
| `--bb-accent-2` | The accent tuned for text and thin strokes. |
|
|
51
|
+
| `--bb-green` | Positive values. |
|
|
52
|
+
| `--bb-red` | Negative values and errors. |
|
|
53
|
+
| `--bb-orange` | Warnings. |
|
|
54
|
+
| `--bb-surface` | Background of a control or card on the tile. |
|
|
55
|
+
| `--bb-surface-hover` | The same, hovered. |
|
|
56
|
+
| `--bb-font` | UI font family. |
|
|
57
|
+
| `--bb-font-display` | Font family for large numbers. |
|
|
58
|
+
| `--bb-fs-xs` | Extra-small font size (captions). |
|
|
59
|
+
| `--bb-fs-sm` | Small font size (body text). |
|
|
60
|
+
| `--bb-fs-lg` | Large font size (values). |
|
|
61
|
+
| `--bb-card-radius` | Corner radius of cards. |
|
|
62
|
+
|
|
63
|
+
Values are resolved where the page sits: a tile gets the dock's colours, a panel gets the
|
|
64
|
+
popup's. They change at runtime, so use the variables rather than copying their values.
|
|
65
|
+
|
|
66
|
+
The list is exported as `THEME_TOKENS`. Removing or renaming a variable is a breaking change
|
|
67
|
+
of the mod API; new ones may be added.
|
|
68
|
+
|
|
69
|
+
## Attributes
|
|
70
|
+
|
|
71
|
+
```html
|
|
72
|
+
<html data-theme="dark" data-material="glass" data-tone="dark" data-surface="tile">
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
| Attribute | Values | Meaning |
|
|
76
|
+
| -------------- | ---------------------------- | --------------------------------------------- |
|
|
77
|
+
| `data-tone` | `light`, `dark` | The tone of the surface the page is on. |
|
|
78
|
+
| `data-theme` | `light`, `dark` | The user's theme. |
|
|
79
|
+
| `data-material`| `solid`, `frost`, `glass` | The dock material. |
|
|
80
|
+
| `data-surface` | `tile`, `panel` | Same as `bb.surface`. |
|
|
81
|
+
| `data-style` | `black`, `white`, `frost`, `glass` | Deprecated: kept for older mods. |
|
|
82
|
+
|
|
83
|
+
Style against `data-tone`, not `data-theme`: they can differ. Liquid glass keeps the dock dark
|
|
84
|
+
in light theme, so a tile can be dark while the theme is light.
|
|
85
|
+
|
|
86
|
+
```css
|
|
87
|
+
.chart-line { stroke: var(--bb-accent-2); }
|
|
88
|
+
[data-tone="light"] .shadow { opacity: 0.4; }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## The theme event
|
|
92
|
+
|
|
93
|
+
The dock updates the variables and attributes for you when the user changes the theme,
|
|
94
|
+
material or accent, so CSS needs nothing more. For canvas or SVG you draw from script, listen
|
|
95
|
+
for the change and read the values:
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
bb.on("theme", (theme) => {
|
|
99
|
+
// theme.tokens["--bb-accent"], theme.attrs.tone, ...
|
|
100
|
+
redraw();
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`Theme` is `{ tokens: Record<ThemeToken, string>, attrs: ThemeAttrs }`, where `attrs` has
|
|
105
|
+
`theme`, `material`, `tone`, `surface` and the deprecated `style`.
|
|
106
|
+
|
|
107
|
+
## Fonts and images
|
|
108
|
+
|
|
109
|
+
- Bundle fonts (`.woff2`, `.woff`) and images (`.png`, `.jpg`, `.gif`, `.webp`, `.svg`) in the
|
|
110
|
+
mod folder and reference them with relative URLs. `data:` URLs work too.
|
|
111
|
+
- Web fonts and images from the internet are blocked by the sandbox.
|
|
112
|
+
|
|
113
|
+
## Sizing
|
|
114
|
+
|
|
115
|
+
The page fills the tile: its width follows the [`sizes`](manifest.md#sizes) entry for the
|
|
116
|
+
current size, and its height is the dock's. Design for the narrowest size you list. To adapt,
|
|
117
|
+
read `bb.size` (and listen for `size`) or use width media queries in CSS. A panel page is
|
|
118
|
+
exactly `panelSize`.
|