@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/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`.
@@ -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).
@@ -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.
@@ -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`.