@overcrow/mcp 0.1.3 → 0.1.5
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/README.md +12 -7
- package/dist/bootstrap/pin.js +19 -1
- package/dist/bootstrap/pin.json +47 -43
- package/dist/cli.js +14 -4
- package/dist/content/docs/en/cli.md +34 -32
- package/dist/content/docs/en/dev-channel.md +5 -5
- package/dist/content/docs/en/elements.md +5 -5
- package/dist/content/docs/en/forms.md +32 -30
- package/dist/content/docs/en/guide.md +16 -16
- package/dist/content/docs/en/index.md +12 -12
- package/dist/content/docs/en/limits.md +5 -4
- package/dist/content/docs/en/logic.md +30 -28
- package/dist/content/docs/en/manifest.md +35 -33
- package/dist/content/docs/en/mcp.md +13 -13
- package/dist/content/docs/en/package.md +7 -7
- package/dist/content/docs/en/publish-keys.md +6 -5
- package/dist/content/docs/en/publishing.md +9 -8
- package/dist/content/docs/en/reference.md +5 -5
- package/dist/content/docs/en/result-shapes.md +3 -3
- package/dist/content/docs/en/sdk.md +11 -11
- package/dist/content/docs/en/security.md +30 -30
- package/dist/content/docs/en/service-reference.md +2 -2
- package/dist/content/docs/en/services.md +33 -32
- package/dist/content/docs/en/style-properties.md +2 -2
- package/dist/content/docs/en/style.md +19 -18
- package/dist/content/docs/en/testing.md +36 -35
- package/dist/content/docs/en/view.md +13 -12
- package/dist/content/docs/en/widget-statistics.md +18 -17
- package/dist/content/docs/en/widgets.md +1 -1
- package/dist/content/docs/fr/cli.md +35 -30
- package/dist/content/docs/fr/dev-channel.md +8 -8
- package/dist/content/docs/fr/elements.md +5 -5
- package/dist/content/docs/fr/forms.md +35 -34
- package/dist/content/docs/fr/guide.md +13 -12
- package/dist/content/docs/fr/index.md +15 -15
- package/dist/content/docs/fr/limits.md +5 -5
- package/dist/content/docs/fr/logic.md +42 -37
- package/dist/content/docs/fr/manifest.md +40 -39
- package/dist/content/docs/fr/mcp.md +21 -19
- package/dist/content/docs/fr/package.md +8 -7
- package/dist/content/docs/fr/publish-keys.md +6 -5
- package/dist/content/docs/fr/publishing.md +8 -8
- package/dist/content/docs/fr/reference.md +6 -6
- package/dist/content/docs/fr/result-shapes.md +4 -3
- package/dist/content/docs/fr/sdk.md +12 -11
- package/dist/content/docs/fr/security.md +41 -39
- package/dist/content/docs/fr/service-reference.md +2 -2
- package/dist/content/docs/fr/services.md +34 -33
- package/dist/content/docs/fr/style-properties.md +2 -2
- package/dist/content/docs/fr/style.md +25 -22
- package/dist/content/docs/fr/testing.md +43 -43
- package/dist/content/docs/fr/view.md +17 -16
- package/dist/content/docs/fr/widget-statistics.md +20 -20
- package/dist/content/docs/fr/widgets.md +1 -1
- package/dist/content/examples/clock/README.md +3 -3
- package/dist/content/examples/fps/README.md +3 -3
- package/dist/content/examples/media/README.md +2 -2
- package/dist/content/examples/notes/README.md +1 -1
- package/dist/content/examples/performance/README.md +2 -2
- package/dist/content/examples/playervox-journal/README.md +5 -5
- package/dist/content/examples/playervox-rating/README.md +3 -3
- package/dist/content/examples/playervox-reviews/README.md +3 -3
- package/dist/content/examples/playervox-score/README.md +3 -3
- package/dist/content/examples/session/README.md +3 -3
- package/dist/content/examples/stopwatch/README.md +3 -3
- package/dist/content/examples/twitch-chat/README.md +4 -4
- package/dist/content/examples/warframe-market/README.md +2 -2
- package/dist/content/reference/errors.json +16 -16
- package/dist/prompts.js +2 -2
- package/dist/resources.js +1 -1
- package/dist/text.js +10 -2
- package/dist/texts.js +1 -1
- package/dist/tools/build.js +16 -10
- package/dist/tools/common.js +19 -12
- package/dist/tools/submission.js +7 -4
- package/dist/typescript.js +38 -0
- package/dist/version.js +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
|
@@ -31,8 +31,8 @@ import {
|
|
|
31
31
|
The SDK is bundled into the widget's `logic.js` when it is packaged, and
|
|
32
32
|
runs inside the widget's VM; loading it anywhere else throws an error.
|
|
33
33
|
Unused parts are removed from the bundle. It is a convenience, not a
|
|
34
|
-
security boundary: OverCrow checks every call, parameter and value
|
|
35
|
-
leaves the VM.
|
|
34
|
+
security boundary: PlayerVox OverCrow checks every call, parameter and value
|
|
35
|
+
that leaves the VM.
|
|
36
36
|
|
|
37
37
|
| Export | Kind | Summary |
|
|
38
38
|
| --- | --- | --- |
|
|
@@ -68,9 +68,9 @@ const state = initState({ values: [50] as number[] });
|
|
|
68
68
|
|
|
69
69
|
| Export | Kind | Summary |
|
|
70
70
|
| --- | --- | --- |
|
|
71
|
-
| `host` | constant | Frozen object whose members always read the latest values sent by OverCrow. |
|
|
71
|
+
| `host` | constant | Frozen object whose members always read the latest values sent by PlayerVox OverCrow. |
|
|
72
72
|
| `HostData` | interface | Type of `host`: `locale`, `messages`, `theme`, `region`, `scale` (in thousandths), `viewport`, `mode`, `visible`, `options`, `grants`. |
|
|
73
|
-
| `onHost(listener)` | function | Calls `listener` with the names of the `host` members that OverCrow just sent (`options` after a menu change, `visible` when shown or hidden, `region`…), before the view is evaluated again. Returns `{ cancel() }`. |
|
|
73
|
+
| `onHost(listener)` | function | Calls `listener` with the names of the `host` members that PlayerVox OverCrow just sent (`options` after a menu change, `visible` when shown or hidden, `region`…), before the view is evaluated again. Returns `{ cancel() }`. |
|
|
74
74
|
| `HostKey` | type | The name of a member of `HostData`. |
|
|
75
75
|
| `HostListener` | type | A listener of `onHost`. |
|
|
76
76
|
| `Viewport` | interface | `{ width, height }`, in logical pixels. |
|
|
@@ -99,8 +99,8 @@ onHost((changed) => {
|
|
|
99
99
|
|
|
100
100
|
## Services
|
|
101
101
|
|
|
102
|
-
Every service answers through OverCrow, which checks its
|
|
103
|
-
capability, its parameters and the user action at each call.
|
|
102
|
+
Every service answers through PlayerVox OverCrow, which checks its
|
|
103
|
+
permission or capability, its parameters and the user action at each call.
|
|
104
104
|
|
|
105
105
|
| Export | Kind | Summary |
|
|
106
106
|
| --- | --- | --- |
|
|
@@ -250,7 +250,7 @@ Month and weekday names, 12-hour clocks and plural rules are not part of
|
|
|
250
250
|
## Generated types
|
|
251
251
|
|
|
252
252
|
These types are generated from the widget schema, so they always match
|
|
253
|
-
what OverCrow accepts.
|
|
253
|
+
what PlayerVox OverCrow accepts.
|
|
254
254
|
|
|
255
255
|
| Export | Summary |
|
|
256
256
|
| --- | --- |
|
|
@@ -289,7 +289,7 @@ constants, so the code never repeats a number: `MAX_TIMERS`,
|
|
|
289
289
|
|
|
290
290
|
## Unit tests: `@overcrow/sdk/testing`
|
|
291
291
|
|
|
292
|
-
A second entry point, never bundled into a widget, replaces
|
|
293
|
-
unit test of the logic: `installRuntime()` gives
|
|
294
|
-
service calls and pushes the subscription values.
|
|
295
|
-
[unit tests](testing.md#unit-tests).
|
|
292
|
+
A second entry point, never bundled into a widget, replaces
|
|
293
|
+
PlayerVox OverCrow in a unit test of the logic: `installRuntime()` gives
|
|
294
|
+
virtual time, settles the service calls and pushes the subscription values.
|
|
295
|
+
See [unit tests](testing.md#unit-tests).
|
|
@@ -23,15 +23,15 @@ Each widget runs behind two barriers.
|
|
|
23
23
|
capabilities, a Job Object per widget, and process mitigations that
|
|
24
24
|
forbid dynamic code and the window system.
|
|
25
25
|
|
|
26
|
-
OverCrow draws everything itself: the VM sends a description of
|
|
27
|
-
never pixels, and never runs code in OverCrow's process. Hover,
|
|
28
|
-
pressed states and transitions are resolved by OverCrow, so a widget
|
|
29
|
-
not observe pointer motion it has not asked for through an event.
|
|
26
|
+
PlayerVox OverCrow draws everything itself: the VM sends a description of
|
|
27
|
+
the view, never pixels, and never runs code in OverCrow's process. Hover,
|
|
28
|
+
focus, pressed states and transitions are resolved by OverCrow, so a widget
|
|
29
|
+
does not observe pointer motion it has not asked for through an event.
|
|
30
30
|
|
|
31
|
-
Going over a budget ends only that widget. OverCrow shows a fixed
|
|
32
|
-
its frame and restarts it after 1, 5 and 15 seconds, at most three
|
|
33
|
-
a package or protocol error waits for the user to enable it again.
|
|
34
|
-
numbers are in [limits](limits.md#logic).
|
|
31
|
+
Going over a budget ends only that widget. PlayerVox OverCrow shows a fixed
|
|
32
|
+
error in its frame and restarts it after 1, 5 and 15 seconds, at most three
|
|
33
|
+
times; a package or protocol error waits for the user to enable it again.
|
|
34
|
+
The numbers are in [limits](limits.md#logic).
|
|
35
35
|
|
|
36
36
|
## Permissions and consent
|
|
37
37
|
|
|
@@ -40,22 +40,22 @@ declaration grants nothing by itself. When the widget is installed, the
|
|
|
40
40
|
Control Center proposes each permission checked, and the user may uncheck
|
|
41
41
|
any. Later, the user allows or takes back each permission in the Control
|
|
42
42
|
Center; taking one back restarts the widget without it.
|
|
43
|
-
OverCrow checks the permission again at every call of a service.
|
|
43
|
+
PlayerVox OverCrow checks the permission again at every call of a service.
|
|
44
44
|
|
|
45
45
|
Four permissions open general services: `network` (exact HTTPS routes,
|
|
46
|
-
through OverCrow's broker), `storage` (a key-value store for this
|
|
47
|
-
only), `clipboardWrite` (writing text, during a user action) and
|
|
46
|
+
through PlayerVox OverCrow's broker), `storage` (a key-value store for this
|
|
47
|
+
widget only), `clipboardWrite` (writing text, during a user action) and
|
|
48
48
|
`gameEvents` (named game events).
|
|
49
49
|
|
|
50
|
-
Capabilities give access to data and actions of OverCrow and of
|
|
51
|
-
accounts. A **sensitive** capability reveals personal data or the
|
|
52
|
-
being played: a widget that declares one cannot also declare `network`
|
|
53
|
-
`clipboardWrite`, and its storage lasts only as long as its process, so
|
|
54
|
-
data cannot leave the machine through the widget.
|
|
50
|
+
Capabilities give access to data and actions of PlayerVox OverCrow and of
|
|
51
|
+
the user's accounts. A **sensitive** capability reveals personal data or the
|
|
52
|
+
game being played: a widget that declares one cannot also declare `network`
|
|
53
|
+
or `clipboardWrite`, and its storage lasts only as long as its process, so
|
|
54
|
+
the data cannot leave the machine through the widget.
|
|
55
55
|
|
|
56
|
-
Account connections (PlayerVox, Twitch) belong to OverCrow:
|
|
57
|
-
and tokens are drawn and kept by OverCrow, and a widget
|
|
58
|
-
data its capability describes.
|
|
56
|
+
Account connections (PlayerVox, Twitch) belong to PlayerVox OverCrow:
|
|
57
|
+
sign-in, codes and tokens are drawn and kept by OverCrow, and a widget
|
|
58
|
+
receives only the data its capability describes.
|
|
59
59
|
|
|
60
60
|
Each permission, each capability and the services it opens are described
|
|
61
61
|
in [services and permissions](services.md). Declare the least you need:
|
|
@@ -70,15 +70,15 @@ Services that change something for the user can be called only while the
|
|
|
70
70
|
logic handles a real action of the user in the widget: a click, a key, an
|
|
71
71
|
edit, a submitted form. A call from a timer, from a service answer or from
|
|
72
72
|
a row of the options menu is refused with `gesture_required`. Widgets
|
|
73
|
-
receive input only in OverCrow's Interactive mode; in Passive mode
|
|
74
|
-
click-through. Deleting a note or a journal session also asks the
|
|
75
|
-
confirm in a dialog drawn by OverCrow. See
|
|
73
|
+
receive input only in PlayerVox OverCrow's Interactive mode; in Passive mode
|
|
74
|
+
they are click-through. Deleting a note or a journal session also asks the
|
|
75
|
+
user to confirm in a dialog drawn by OverCrow. See
|
|
76
76
|
[calls that need a user action](services.md#calls-that-need-a-user-action).
|
|
77
77
|
|
|
78
78
|
What the user writes to notes, ratings and chat never passes through your
|
|
79
79
|
logic: a `form` with an `intent` sends the values of its own text fields and
|
|
80
|
-
sliders, which OverCrow fills, edits and submits itself. Your
|
|
81
|
-
them, not set them. See
|
|
80
|
+
sliders, which PlayerVox OverCrow fills, edits and submits itself. Your
|
|
81
|
+
logic can read them, not set them. See
|
|
82
82
|
[forms that write user data](forms.md#forms-that-write-user-data).
|
|
83
83
|
|
|
84
84
|
## What a widget cannot do
|
|
@@ -88,9 +88,9 @@ them, not set them. See
|
|
|
88
88
|
- Start processes, load native code, compile code at runtime or fetch code:
|
|
89
89
|
the only code is the reviewed `logic.js` of the package.
|
|
90
90
|
- See other widgets, their state, storage or permissions, or the game's
|
|
91
|
-
memory, window or input. OverCrow never injects into the game.
|
|
92
|
-
- Draw outside its frame, cover or imitate OverCrow's frame, menus
|
|
93
|
-
confirmations.
|
|
91
|
+
memory, window or input. PlayerVox OverCrow never injects into the game.
|
|
92
|
+
- Draw outside its frame, cover or imitate PlayerVox OverCrow's frame, menus
|
|
93
|
+
or confirmations.
|
|
94
94
|
- Read account tokens, cookies or credentials.
|
|
95
95
|
- Read the clipboard.
|
|
96
96
|
- Write to logs in production: `log.*` output appears only in a local
|
|
@@ -100,13 +100,13 @@ them, not set them. See
|
|
|
100
100
|
## What OverCrow verifies
|
|
101
101
|
|
|
102
102
|
Every package is checked when it is admitted to the catalog and again each
|
|
103
|
-
time OverCrow starts it: the signed catalog, the ledger of its
|
|
104
|
-
the compiled view must match, or the widget does not start. See
|
|
103
|
+
time PlayerVox OverCrow starts it: the signed catalog, the ledger of its
|
|
104
|
+
files and the compiled view must match, or the widget does not start. See
|
|
105
105
|
[the package](package.md#how-overcrow-checks-a-package) and
|
|
106
106
|
[publishing and review](publishing.md).
|
|
107
107
|
|
|
108
108
|
A version of the catalog can be suspended or revoked after its
|
|
109
|
-
publication: OverCrow then stops the installed copy. See
|
|
109
|
+
publication: PlayerVox OverCrow then stops the installed copy. See
|
|
110
110
|
[version statuses](publishing.md#version-statuses).
|
|
111
111
|
|
|
112
112
|
## Reporting a vulnerability
|
|
@@ -229,7 +229,7 @@ update.
|
|
|
229
229
|
|
|
230
230
|
### `notes.delete`
|
|
231
231
|
|
|
232
|
-
- **Kind**: call, answered once; the user confirms it first, in a dialog drawn by OverCrow
|
|
232
|
+
- **Kind**: call, answered once; the user confirms it first, in a dialog drawn by PlayerVox OverCrow
|
|
233
233
|
- **Requires**: capability `notes.write`
|
|
234
234
|
- **When it can be called**: Only during a user action
|
|
235
235
|
- **Parameters**: `note`: text ≤ 128 bytes
|
|
@@ -292,7 +292,7 @@ update.
|
|
|
292
292
|
|
|
293
293
|
### `journal.delete`
|
|
294
294
|
|
|
295
|
-
- **Kind**: call, answered once; the user confirms it first, in a dialog drawn by OverCrow
|
|
295
|
+
- **Kind**: call, answered once; the user confirms it first, in a dialog drawn by PlayerVox OverCrow
|
|
296
296
|
- **Requires**: capability `journal.delete`
|
|
297
297
|
- **When it can be called**: Only during a user action
|
|
298
298
|
- **Parameters**: `session`: text ≤ 128 bytes
|
|
@@ -28,8 +28,8 @@ Two kinds of authority exist, both declared in `permissions` of
|
|
|
28
28
|
- four **permissions** for general services: `network`, `storage`,
|
|
29
29
|
`clipboardWrite` and `gameEvents`;
|
|
30
30
|
- **capabilities**, listed under `permissions.capabilities`, for the data
|
|
31
|
-
and actions of OverCrow itself and of the user's accounts: the
|
|
32
|
-
rate, the media player, notes, PlayerVox ratings, Twitch chat…
|
|
31
|
+
and actions of PlayerVox OverCrow itself and of the user's accounts: the
|
|
32
|
+
frame rate, the media player, notes, PlayerVox ratings, Twitch chat…
|
|
33
33
|
|
|
34
34
|
<!-- source: docs/content/examples/weather/manifest.json -->
|
|
35
35
|
```json
|
|
@@ -89,9 +89,9 @@ async function readStored(key: string): Promise<JsonValue | undefined> {
|
|
|
89
89
|
}
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
-
**A subscription** takes a listener. OverCrow calls it with the
|
|
93
|
-
value at once, then with each new value, until you `cancel()` it or
|
|
94
|
-
ends with a failure. The listener comes last; a service with parameters
|
|
92
|
+
**A subscription** takes a listener. PlayerVox OverCrow calls it with the
|
|
93
|
+
current value at once, then with each new value, until you `cancel()` it or
|
|
94
|
+
it ends with a failure. The listener comes last; a service with parameters
|
|
95
95
|
takes them first.
|
|
96
96
|
|
|
97
97
|
<!-- source: widgets/media/logic.ts -->
|
|
@@ -123,10 +123,10 @@ Services are grouped in namespaces of the SDK: `storage`, `http`,
|
|
|
123
123
|
`twitch`). Every service, with its parameters and its result, is in the
|
|
124
124
|
[service reference](service-reference.md).
|
|
125
125
|
|
|
126
|
-
OverCrow checks every call when it arrives, in this order: the
|
|
127
|
-
or capability, the parameters, the user action when the service
|
|
128
|
-
then the account when it needs one. The SDK's types help you call
|
|
129
|
-
service right; they are not what enforces the rules.
|
|
126
|
+
PlayerVox OverCrow checks every call when it arrives, in this order: the
|
|
127
|
+
permission or capability, the parameters, the user action when the service
|
|
128
|
+
needs one, then the account when it needs one. The SDK's types help you call
|
|
129
|
+
a service right; they are not what enforces the rules.
|
|
130
130
|
|
|
131
131
|
## Errors
|
|
132
132
|
|
|
@@ -160,20 +160,20 @@ subscription that fails delivers the same error in its last update.
|
|
|
160
160
|
| `gesture_required` | The service can be called only during a user action, and this call was not made while one was handled, or that action already allowed another call. |
|
|
161
161
|
| `not_connected` | The service needs the user's PlayerVox or Twitch account, which is not connected at the moment. |
|
|
162
162
|
| `stale_context` | What the call was about changed before the answer: another game, another account, another media player, an object deleted meanwhile. Read the current state again. |
|
|
163
|
-
| `unavailable` | OverCrow's source for this data failed, or cannot act right now. A subscription that ends with it can be started again later. |
|
|
163
|
+
| `unavailable` | PlayerVox OverCrow's source for this data failed, or cannot act right now. A subscription that ends with it can be started again later. |
|
|
164
164
|
| `busy` | Too much is in progress: a confirmation is already open, a queue or the budget of network responses is full, or the provider asks to wait. Try again later. |
|
|
165
165
|
| `cancelled` | The user declined the confirmation, or left Interactive mode while it was open. |
|
|
166
166
|
| `quota_exceeded` | A quota is full: the storage, the timers, the notes, the favourite channels. |
|
|
167
167
|
| `unsupported` | The target cannot do this: a media player that does not offer the command, for instance. |
|
|
168
|
-
| `url_invalid` | `http.fetch`: the URL is not an absolute HTTPS URL that OverCrow accepts. |
|
|
168
|
+
| `url_invalid` | `http.fetch`: the URL is not an absolute HTTPS URL that PlayerVox OverCrow accepts. |
|
|
169
169
|
| `resolve_failed` | `http.fetch`: the host name could not be resolved. |
|
|
170
170
|
| `address_denied` | `http.fetch`: the host name resolves to a local, private or otherwise non-public address. |
|
|
171
|
-
| `too_many_addresses` | `http.fetch`: the host name resolves to more addresses than OverCrow accepts. |
|
|
171
|
+
| `too_many_addresses` | `http.fetch`: the host name resolves to more addresses than PlayerVox OverCrow accepts. |
|
|
172
172
|
| `peer_mismatch` | `http.fetch`: the server that answered is not at one of the addresses that were resolved and checked. |
|
|
173
|
-
| `redirect_denied` | `http.fetch`: the server answered with a redirection. OverCrow follows none: declare and request the final URL. |
|
|
174
|
-
| `encoding_denied` | `http.fetch`: the response is compressed or encoded in a way OverCrow does not accept, or its body does not decode as `as` asks (invalid JSON or text). |
|
|
175
|
-
| `content_type_denied` | `http.fetch`: the media type of the response is not one that OverCrow accepts for this request. |
|
|
176
|
-
| `response_metadata_limit` | `http.fetch`: the status line or the headers of the response are malformed or exceed OverCrow's bounds. |
|
|
173
|
+
| `redirect_denied` | `http.fetch`: the server answered with a redirection. PlayerVox OverCrow follows none: declare and request the final URL. |
|
|
174
|
+
| `encoding_denied` | `http.fetch`: the response is compressed or encoded in a way PlayerVox OverCrow does not accept, or its body does not decode as `as` asks (invalid JSON or text). |
|
|
175
|
+
| `content_type_denied` | `http.fetch`: the media type of the response is not one that PlayerVox OverCrow accepts for this request. |
|
|
176
|
+
| `response_metadata_limit` | `http.fetch`: the status line or the headers of the response are malformed or exceed PlayerVox OverCrow's bounds. |
|
|
177
177
|
| `request_body_limit` | `http.fetch`: the request body is larger than 256 KiB. |
|
|
178
178
|
| `response_body_limit` | `http.fetch`: the response body is larger than the bound of the network rule (`maxResponseBytes`, or 1 MiB without it and for `as: "image"`). |
|
|
179
179
|
| `image_invalid` | `http.fetch` with `as: "image"`: the response is not a PNG, JPEG or WebP image within the image limits. |
|
|
@@ -185,8 +185,8 @@ Three habits cover most cases:
|
|
|
185
185
|
|
|
186
186
|
- **Show a state, not an error message.** The codes are for your logic;
|
|
187
187
|
the user sees "Forecast unavailable", not `transport_failed`.
|
|
188
|
-
- **Retry a subscription that ended.** A source of OverCrow can
|
|
189
|
-
the widget runs (the media player's session, for instance): the
|
|
188
|
+
- **Retry a subscription that ended.** A source of PlayerVox OverCrow can
|
|
189
|
+
fail while the widget runs (the media player's session, for instance): the
|
|
190
190
|
subscription ends with `unavailable`. Subscribe again a few seconds later
|
|
191
191
|
with `timers.after`; OverCrow restarts the source for the new
|
|
192
192
|
subscription. The Media widget waits five seconds:
|
|
@@ -231,10 +231,11 @@ The same call from a timer, from the answer of another service, from
|
|
|
231
231
|
|
|
232
232
|
- One user action allows one protected call. Call the service directly in
|
|
233
233
|
the handler, not after an `await` on something else.
|
|
234
|
-
- Widgets receive input only in OverCrow's Interactive mode, so a
|
|
235
|
-
call can only happen there.
|
|
234
|
+
- Widgets receive input only in PlayerVox OverCrow's Interactive mode, so a
|
|
235
|
+
protected call can only happen there.
|
|
236
236
|
- `notes.delete` and `journal.delete` also ask the user to confirm, in a
|
|
237
|
-
dialog drawn by OverCrow; a declined confirmation is
|
|
237
|
+
dialog drawn by PlayerVox OverCrow; a declined confirmation is
|
|
238
|
+
`cancelled`.
|
|
238
239
|
|
|
239
240
|
The tables below say, for each service, when it can be called.
|
|
240
241
|
|
|
@@ -326,8 +327,8 @@ Each path and query parameter has a constraint:
|
|
|
326
327
|
| `string` | `{ maxLength }` | Query parameters only; any text without control characters; `maxLength` from 1 to 256 bytes. |
|
|
327
328
|
<!-- /generated:parameter-constraints -->
|
|
328
329
|
|
|
329
|
-
The request leaves through OverCrow's broker, never from the
|
|
330
|
-
process. The broker:
|
|
330
|
+
The request leaves through PlayerVox OverCrow's broker, never from the
|
|
331
|
+
widget's process. The broker:
|
|
331
332
|
|
|
332
333
|
- refuses any URL that no rule allows (`permission_denied`), before any
|
|
333
334
|
DNS query;
|
|
@@ -363,8 +364,8 @@ once.
|
|
|
363
364
|
|
|
364
365
|
### Storage
|
|
365
366
|
|
|
366
|
-
`storage` is a key-value store that OverCrow keeps for your widget
|
|
367
|
-
`storage.get({ key })`, `storage.set({ key, value })`,
|
|
367
|
+
`storage` is a key-value store that PlayerVox OverCrow keeps for your widget
|
|
368
|
+
only: `storage.get({ key })`, `storage.set({ key, value })`,
|
|
368
369
|
`storage.remove({ key })` and `storage.keys()`. A value is any JSON value.
|
|
369
370
|
There is no file access.
|
|
370
371
|
|
|
@@ -403,7 +404,7 @@ user action. A widget cannot read the clipboard.
|
|
|
403
404
|
```
|
|
404
405
|
|
|
405
406
|
Text that the user selects in a `text` element with the `selectable`
|
|
406
|
-
attribute is copied by OverCrow itself, and needs no permission.
|
|
407
|
+
attribute is copied by PlayerVox OverCrow itself, and needs no permission.
|
|
407
408
|
|
|
408
409
|
### Game events
|
|
409
410
|
|
|
@@ -413,9 +414,9 @@ attribute is copied by OverCrow itself, and needs no permission.
|
|
|
413
414
|
|
|
414
415
|
## Capabilities
|
|
415
416
|
|
|
416
|
-
A capability gives access to data or actions that OverCrow holds:
|
|
417
|
-
game's use of the machine, the media player, the user's notes,
|
|
418
|
-
PlayerVox and Twitch accounts.
|
|
417
|
+
A capability gives access to data or actions that PlayerVox OverCrow holds:
|
|
418
|
+
what the game's use of the machine, the media player, the user's notes,
|
|
419
|
+
their PlayerVox and Twitch accounts.
|
|
419
420
|
|
|
420
421
|
<!-- generated:capability-list -->
|
|
421
422
|
| Capability | Sensitive | Account | Meaning |
|
|
@@ -494,9 +495,9 @@ widget needs both an HTTP API and a sensitive capability, make two widgets.
|
|
|
494
495
|
### Accounts
|
|
495
496
|
|
|
496
497
|
Some capabilities need the user's PlayerVox or Twitch account. The
|
|
497
|
-
connection belongs to OverCrow: it draws the sign-in, keeps the
|
|
498
|
-
shows its own panel over the widget while the account is signed
|
|
499
|
-
widget never sees a token; it receives only the data its capability
|
|
498
|
+
connection belongs to PlayerVox OverCrow: it draws the sign-in, keeps the
|
|
499
|
+
tokens and shows its own panel over the widget while the account is signed
|
|
500
|
+
out. A widget never sees a token; it receives only the data its capability
|
|
500
501
|
describes, and its calls fail with `not_connected` while the account is
|
|
501
502
|
not connected.
|
|
502
503
|
|
|
@@ -266,5 +266,5 @@ Lucide 1.34.0, 1777 icons.
|
|
|
266
266
|
|
|
267
267
|
Any other name is refused, and the SDK's `IconName` type lists them all, so
|
|
268
268
|
a wrong name in the logic is a TypeScript error. Within API v1 the set may
|
|
269
|
-
grow but never loses or renames an icon. OverCrow draws the icons
|
|
270
|
-
widget ships no icon font.
|
|
269
|
+
grow but never loses or renames an icon. PlayerVox OverCrow draws the icons
|
|
270
|
+
itself: a widget ships no icon font.
|
|
@@ -79,9 +79,9 @@ states: `button.primary:hover`. Compounds are joined by a space
|
|
|
79
79
|
}
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
The states are resolved by OverCrow, not by your logic: `:hover`
|
|
83
|
-
`:active` follow the pointer, `:focus` the keyboard focus, `:disabled`
|
|
84
|
-
`disabled` attribute, and `:checked` the state of a `toggle` or
|
|
82
|
+
The states are resolved by PlayerVox OverCrow, not by your logic: `:hover`
|
|
83
|
+
and `:active` follow the pointer, `:focus` the keyboard focus, `:disabled`
|
|
84
|
+
the `disabled` attribute, and `:checked` the state of a `toggle` or
|
|
85
85
|
`checkbox`. A widget is not told about pointer moves: a hover effect costs
|
|
86
86
|
it nothing.
|
|
87
87
|
|
|
@@ -134,7 +134,7 @@ how the countdown example puts the time in the middle of its ring:
|
|
|
134
134
|
}
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
-
A widget cannot draw outside its frame: OverCrow clips it.
|
|
137
|
+
A widget cannot draw outside its frame: PlayerVox OverCrow clips it.
|
|
138
138
|
|
|
139
139
|
## Values
|
|
140
140
|
|
|
@@ -144,17 +144,17 @@ the unit) and percentages, colours as `#rrggbb`, `#rrggbbaa` or
|
|
|
144
144
|
tokens as `var(--name)`. The exact notation of each kind of value is in
|
|
145
145
|
[values](style-properties.md#values).
|
|
146
146
|
|
|
147
|
-
Lengths are logical pixels: OverCrow multiplies them by the user's
|
|
148
|
-
scale (50 % to 175 %) and by the screen's density, so `12px` is the
|
|
149
|
-
physical size on every screen. Shorthands expand as in CSS: one to four
|
|
147
|
+
Lengths are logical pixels: PlayerVox OverCrow multiplies them by the user's
|
|
148
|
+
content scale (50 % to 175 %) and by the screen's density, so `12px` is the
|
|
149
|
+
same physical size on every screen. Shorthands expand as in CSS: one to four
|
|
150
150
|
values for sides and corners, one or two for gaps.
|
|
151
151
|
|
|
152
152
|
## Design tokens
|
|
153
153
|
|
|
154
|
-
A token is a value of OverCrow's design system, written
|
|
155
|
-
Colour tokens change with the user's theme, light or dark: a
|
|
156
|
-
with tokens follows the theme without any code. Prefer them to
|
|
157
|
-
colours.
|
|
154
|
+
A token is a value of PlayerVox OverCrow's design system, written
|
|
155
|
+
`var(--name)`. Colour tokens change with the user's theme, light or dark: a
|
|
156
|
+
widget styled with tokens follows the theme without any code. Prefer them to
|
|
157
|
+
literal colours.
|
|
158
158
|
|
|
159
159
|
<!-- source: docs/content/examples/countdown/style.ocss -->
|
|
160
160
|
```css
|
|
@@ -176,8 +176,9 @@ length. There is no fallback argument, and a widget cannot declare its own
|
|
|
176
176
|
custom properties. All tokens are listed in
|
|
177
177
|
[design tokens](style-properties.md#design-tokens).
|
|
178
178
|
|
|
179
|
-
OverCrow draws the panel behind the widget
|
|
180
|
-
frame and its shadow: start from a
|
|
179
|
+
PlayerVox OverCrow draws the panel behind the widget
|
|
180
|
+
(`--color-surface-panel`), its frame and its shadow: start from a
|
|
181
|
+
transparent background.
|
|
181
182
|
|
|
182
183
|
## Text
|
|
183
184
|
|
|
@@ -187,8 +188,8 @@ container to style what it holds.
|
|
|
187
188
|
|
|
188
189
|
- Three font families exist: `ui` (Noto Sans, the default), `mono` (Noto
|
|
189
190
|
Sans Mono, for values) and `display` (Space Grotesk, for grades and
|
|
190
|
-
scores). OverCrow bundles them; system fonts are never used, so
|
|
191
|
-
looks the same on every machine.
|
|
191
|
+
scores). PlayerVox OverCrow bundles them; system fonts are never used, so
|
|
192
|
+
a widget looks the same on every machine.
|
|
192
193
|
- `font-variant-numeric: tabular-nums` gives digits one width, so a
|
|
193
194
|
changing number does not move its neighbours.
|
|
194
195
|
- `text-overflow: ellipsis` cuts an overflowing line with `…`;
|
|
@@ -224,9 +225,9 @@ plays a `@keyframes` block of the same sheet.
|
|
|
224
225
|
|
|
225
226
|
Only properties that change paint, not layout, can be animated:
|
|
226
227
|
`opacity`, `color`, `background-color`, `border-color` and `transform`.
|
|
227
|
-
A `@keyframes` block holds only those. OverCrow runs the animation
|
|
228
|
-
no timer and no code of the widget run while it plays, and nothing
|
|
229
|
-
repainted when nothing changes. A widget that is hidden does not animate.
|
|
228
|
+
A `@keyframes` block holds only those. PlayerVox OverCrow runs the animation
|
|
229
|
+
itself: no timer and no code of the widget run while it plays, and nothing
|
|
230
|
+
is repainted when nothing changes. A widget that is hidden does not animate.
|
|
230
231
|
|
|
231
232
|
`@keyframes` is the only at-rule. Its name is an identifier that is not an
|
|
232
233
|
animation keyword, unique in the sheet.
|
|
@@ -5,9 +5,9 @@ a game or an account:
|
|
|
5
5
|
|
|
6
6
|
- **Unit tests of the logic**, in Node.js, with `@overcrow/sdk/testing`:
|
|
7
7
|
fast, for the functions of `logic.ts`.
|
|
8
|
-
- **Scenarios**, played by `overcrow-widget test` in OverCrow's
|
|
9
|
-
runtime**: the real VM, style, layout and renderer, OverCrow's
|
|
10
|
-
checks, simulated services, virtual time and reference images. What
|
|
8
|
+
- **Scenarios**, played by `overcrow-widget test` in PlayerVox OverCrow's
|
|
9
|
+
**headless runtime**: the real VM, style, layout and renderer, OverCrow's
|
|
10
|
+
own checks, simulated services, virtual time and reference images. What
|
|
11
11
|
passes there is what the overlay shows.
|
|
12
12
|
|
|
13
13
|
<!-- source: templates/counter/tests/example.scenario.json -->
|
|
@@ -35,8 +35,8 @@ is "Increase", then checks the new text and image.
|
|
|
35
35
|
by `overcrow-widget init`, otherwise
|
|
36
36
|
`npm install --save-dev --save-exact @overcrow/sdk@1.0.0`.
|
|
37
37
|
|
|
38
|
-
`installRuntime()` puts a stand-in for OverCrow in place before
|
|
39
|
-
is imported: service calls return promises that your test settles,
|
|
38
|
+
`installRuntime()` puts a stand-in for PlayerVox OverCrow in place before
|
|
39
|
+
the logic is imported: service calls return promises that your test settles,
|
|
40
40
|
subscriptions take the values you push, timers fire when you advance the
|
|
41
41
|
time, and `Date.now()` is virtual.
|
|
42
42
|
|
|
@@ -74,17 +74,17 @@ test("one timer at the next local minute, then each minute", () => {
|
|
|
74
74
|
| --- | --- |
|
|
75
75
|
| `installRuntime({ now, host })` | Installs the stand-in; `Date.now()` returns the virtual time. One at a time. |
|
|
76
76
|
| `now`, `advance(ms)` | The virtual time; `advance` fires the timers that fall due, in order (a repeating one re-arms), and returns their count. |
|
|
77
|
-
| `setHost(changes)` | Changes `host` as OverCrow does: `region`, `locale`, `options`… |
|
|
77
|
+
| `setHost(changes)` | Changes `host` as PlayerVox OverCrow does: `region`, `locale`, `options`… |
|
|
78
78
|
| `calls`, `lastCall(service)` | Every service call, with `resolve(value)` and `reject(code)`. |
|
|
79
79
|
| `push(service, value)`, `fail(service, code)` | The next update, or the final failure, of the subscriptions to a service. |
|
|
80
80
|
| `menu(row)` | Chooses an `action` row of the options menu. |
|
|
81
81
|
| `draws`, `logs`, `timers`, `table` | What the logic sent: canvas drawings, logs, timers, and the functions of the view. |
|
|
82
82
|
| `uninstall()` | Removes the stand-in and gives `Date.now` back. |
|
|
83
83
|
|
|
84
|
-
The stand-in runs your logic only: it does not apply OverCrow's
|
|
85
|
-
grants, the accounts, the user-action rule) and renders nothing.
|
|
86
|
-
do. The reference widgets compile their `logic.ts` with a small
|
|
87
|
-
before importing it:
|
|
84
|
+
The stand-in runs your logic only: it does not apply PlayerVox OverCrow's
|
|
85
|
+
rules (the grants, the accounts, the user-action rule) and renders nothing.
|
|
86
|
+
Scenarios do. The reference widgets compile their `logic.ts` with a small
|
|
87
|
+
loader before importing it:
|
|
88
88
|
|
|
89
89
|
<!-- source: widgets/clock/tests/load-logic.mjs -->
|
|
90
90
|
```js
|
|
@@ -143,13 +143,13 @@ Everything is optional.
|
|
|
143
143
|
| `size` | the manifest's preferred size | `{ width, height }` of the frame, in logical pixels; the manifest's `fit` still applies. |
|
|
144
144
|
| `mode` | `passive` | `interactive` gives input to the widget. |
|
|
145
145
|
| `visible` | `true` | Hidden, the widget gets no timer tick. |
|
|
146
|
-
| `frame` | `false` | `true` captures OverCrow's frame around the content. |
|
|
146
|
+
| `frame` | `false` | `true` captures PlayerVox OverCrow's frame around the content. |
|
|
147
147
|
| `background` | the theme's panel colour | `#rrggbb` behind the widget. |
|
|
148
148
|
| `region` | `us`, date order of the locale | `{ numberFormat, dateOrder }`. |
|
|
149
149
|
| `zone` | UTC | `{ offsetMinutes, transitions: [{ at, offsetMinutes }] }`: the user's UTC offset, and the instants at which it changes. |
|
|
150
150
|
| `startAt` | 2026-01-01T00:00:00Z | The virtual time at which the widget starts, in Unix milliseconds. |
|
|
151
151
|
| `options` | the rows' defaults | Values of the rows of the options menu. |
|
|
152
|
-
| `grants` | `"declared"` | Or the exact list of what the user granted (`storage`, `network`, `fps.read`…): OverCrow refuses the rest. |
|
|
152
|
+
| `grants` | `"declared"` | Or the exact list of what the user granted (`storage`, `network`, `fps.read`…): PlayerVox OverCrow refuses the rest. |
|
|
153
153
|
| `accounts` | connected | `{ playervox, twitch }`, each `connected`, `disconnected`, `pending`, `expired` or `offline`. |
|
|
154
154
|
| `features` | all | The data sources of the machine, for `requires`. |
|
|
155
155
|
| `storage` | empty | The widget's storage before it starts. |
|
|
@@ -174,15 +174,16 @@ Everything is optional.
|
|
|
174
174
|
},
|
|
175
175
|
```
|
|
176
176
|
|
|
177
|
-
With an account that is not `connected`, OverCrow draws its own
|
|
178
|
-
panel over the widget, as it does for the user; capture it with
|
|
177
|
+
With an account that is not `connected`, PlayerVox OverCrow draws its own
|
|
178
|
+
account panel over the widget, as it does for the user; capture it with
|
|
179
|
+
`frame`.
|
|
179
180
|
|
|
180
181
|
### `fixtures`
|
|
181
182
|
|
|
182
|
-
Fixtures replace where the data comes from, never OverCrow's
|
|
183
|
-
first passes the grants, its parameters, the user-action rule
|
|
184
|
-
account check, exactly as in the overlay; only then does a fixture
|
|
185
|
-
it. Every value must have the shape of the service's
|
|
183
|
+
Fixtures replace where the data comes from, never PlayerVox OverCrow's
|
|
184
|
+
checks. A call first passes the grants, its parameters, the user-action rule
|
|
185
|
+
and the account check, exactly as in the overlay; only then does a fixture
|
|
186
|
+
answer it. Every value must have the shape of the service's
|
|
186
187
|
[result](result-shapes.md): one that does not is an error of the scenario,
|
|
187
188
|
not of the widget.
|
|
188
189
|
|
|
@@ -191,7 +192,7 @@ not of the widget.
|
|
|
191
192
|
| `subscriptions` | The value of a subscription when it starts; `publish` steps send the next ones. |
|
|
192
193
|
| `calls` | The calls of a service, in order: `{ "value": … }` or `{ "error": code }`. A call beyond them is an error of the scenario. |
|
|
193
194
|
| `http` | The `http.fetch` requests, each used once: `{ "request": { method, url }, "response": { status, contentType, body } }` (or `bodyBase64`), or `{ "request": …, "error": code }`. The manifest's network rules apply first, and the response bounds apply as in the overlay. |
|
|
194
|
-
| `confirmations` | `accept` or `cancel`, in order, for OverCrow's confirmation of `notes.delete` and `journal.delete`. |
|
|
195
|
+
| `confirmations` | `accept` or `cancel`, in order, for PlayerVox OverCrow's confirmation of `notes.delete` and `journal.delete`. |
|
|
195
196
|
| `intents` | The answer to each submitted [write intent](forms.md#forms-that-write-user-data), in order: `"accepted"`, `{ "error": code }` or `"pending"`. |
|
|
196
197
|
|
|
197
198
|
<!-- source: widgets/stopwatch/tests/errors.scenario.json -->
|
|
@@ -267,7 +268,7 @@ not of the widget.
|
|
|
267
268
|
]
|
|
268
269
|
```
|
|
269
270
|
|
|
270
|
-
The codes that OverCrow gives itself (`permission_denied`,
|
|
271
|
+
The codes that PlayerVox OverCrow gives itself (`permission_denied`,
|
|
271
272
|
`gesture_required`, `not_connected`, `invalid_request`) cannot be written
|
|
272
273
|
in a fixture: get them the real way, with `grants`, `accounts`, a call
|
|
273
274
|
outside a user action, or wrong parameters. Storage, timers and the
|
|
@@ -275,9 +276,9 @@ clipboard are OverCrow's own and need no fixture.
|
|
|
275
276
|
|
|
276
277
|
### `assets`
|
|
277
278
|
|
|
278
|
-
Images that a fixture hands to the widget, as OverCrow hands it a
|
|
279
|
-
cover or a chat emote: `{ "<name>": "<path>" }`, at most 8, each a PNG
|
|
280
|
-
JPEG of the project (`tests/assets/cover.png`). Where a result holds an
|
|
279
|
+
Images that a fixture hands to the widget, as PlayerVox OverCrow hands it a
|
|
280
|
+
media cover or a chat emote: `{ "<name>": "<path>" }`, at most 8, each a PNG
|
|
281
|
+
or JPEG of the project (`tests/assets/cover.png`). Where a result holds an
|
|
281
282
|
image handle, the fixture writes `"fixture:<name>"`.
|
|
282
283
|
|
|
283
284
|
### `steps`
|
|
@@ -313,7 +314,7 @@ was sent and nothing is in flight. There is no real waiting.
|
|
|
313
314
|
| `state` | `starting`, `running`, `restarting`, `failed`, `refused` or `stopped`. |
|
|
314
315
|
| `fault` | The last fault of the widget's VM, or `none`. |
|
|
315
316
|
| `clipboard` | The last text the widget wrote to the clipboard. |
|
|
316
|
-
| `intents` | Exactly these write intents were submitted since the previous `intents` expectation, in order: `{ intent, fields?, outcome? }`. `fields` are the exact values OverCrow's form sent. |
|
|
317
|
+
| `intents` | Exactly these write intents were submitted since the previous `intents` expectation, in order: `{ intent, fields?, outcome? }`. `fields` are the exact values PlayerVox OverCrow's form sent. |
|
|
317
318
|
|
|
318
319
|
<!-- source: templates/chart/tests/example.scenario.json -->
|
|
319
320
|
```json
|
|
@@ -365,7 +366,7 @@ bytes, on Linux and on Windows.
|
|
|
365
366
|
- Time is virtual: `Date.now()` and `new Date()` return the scenario's
|
|
366
367
|
time, timers fire when the scenario moves it.
|
|
367
368
|
- `Math.random()` is seeded with a fixed value.
|
|
368
|
-
- Text uses the fonts bundled with OverCrow, never the system's.
|
|
369
|
+
- Text uses the fonts bundled with PlayerVox OverCrow, never the system's.
|
|
369
370
|
- Rendering does not depend on the graphics card.
|
|
370
371
|
|
|
371
372
|
This holds for the test runtime only: in the overlay, time and randomness
|
|
@@ -373,22 +374,22 @@ are real.
|
|
|
373
374
|
|
|
374
375
|
## The headless runtime
|
|
375
376
|
|
|
376
|
-
`overcrow-widget-headless` is OverCrow's own code without a
|
|
377
|
-
validates the package as the overlay does and runs the widget's
|
|
378
|
-
the same sandbox. `overcrow-widget test` runs the version this CLI
|
|
379
|
-
0.7.
|
|
380
|
-
system's sandbox the runtime refuses to run and says so; the test
|
|
381
|
-
then ends with status 2.
|
|
377
|
+
`overcrow-widget-headless` is PlayerVox OverCrow's own code without a
|
|
378
|
+
window: it validates the package as the overlay does and runs the widget's
|
|
379
|
+
logic in the same sandbox. `overcrow-widget test` runs the version this CLI
|
|
380
|
+
pins, 0.7.2-beta.1, and prints its version and SHA-256. Without the
|
|
381
|
+
operating system's sandbox the runtime refuses to run and says so; the test
|
|
382
|
+
command then ends with status 2.
|
|
382
383
|
|
|
383
384
|
The first time `test` needs the runtime, it downloads it: from the
|
|
384
|
-
creator tools ZIP of your platform in the OverCrow release that
|
|
385
|
+
creator tools ZIP of your platform in the PlayerVox OverCrow release that
|
|
385
386
|
published it, it keeps only the runtime, and only once its SHA-256 is the
|
|
386
387
|
one this CLI pins. The ZIP is not kept. The runtime then stays in the CLI's cache:
|
|
387
388
|
|
|
388
389
|
| Platform | Path |
|
|
389
390
|
| --- | --- |
|
|
390
|
-
| Linux | `~/.cache/overcrow-widget/runtime/0.7.
|
|
391
|
-
| Windows | `%LOCALAPPDATA%\overcrow-widget\runtime\0.7.
|
|
391
|
+
| Linux | `~/.cache/overcrow-widget/runtime/0.7.2-beta.1/` (`$XDG_CACHE_HOME` instead of `~/.cache` when set) |
|
|
392
|
+
| Windows | `%LOCALAPPDATA%\overcrow-widget\runtime\0.7.2-beta.1\` |
|
|
392
393
|
|
|
393
394
|
To work offline, put the runtime of the creator tools ZIP there yourself
|
|
394
395
|
(executable on Linux): `test` finds it and downloads nothing. With
|
|
@@ -397,4 +398,4 @@ To work offline, put the runtime of the creator tools ZIP there yourself
|
|
|
397
398
|
The CLI checks its SHA-256 before every run. When a download fails,
|
|
398
399
|
nothing is kept and `test` says to try again or to pass `--runtime`.
|
|
399
400
|
`--runtime <path>` runs another runtime instead, such as one built from
|
|
400
|
-
OverCrow; the output then says it is not the pinned one.
|
|
401
|
+
PlayerVox OverCrow; the output then says it is not the pinned one.
|