@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
|
@@ -5,8 +5,8 @@ submission: create a project, edit its view, style and logic, run it in
|
|
|
5
5
|
OverCrow, test it, package it and submit it. Each step links to the page
|
|
6
6
|
that covers it in full.
|
|
7
7
|
|
|
8
|
-
To work with an AI assistant instead, add OverCrow's MCP server to
|
|
9
|
-
[MCP](mcp.md).
|
|
8
|
+
To work with an AI assistant instead, add PlayerVox OverCrow's MCP server to
|
|
9
|
+
it: see [MCP](mcp.md).
|
|
10
10
|
|
|
11
11
|
## 1. Install the tools
|
|
12
12
|
|
|
@@ -15,7 +15,7 @@ To work with an AI assistant instead, add OverCrow's MCP server to it: see
|
|
|
15
15
|
- **Node.js 22 or later** and npm, so that `check` can type-check your
|
|
16
16
|
logic with the project's own TypeScript and the SDK from npm. The CLI checks and packages without it, but
|
|
17
17
|
warns that types were not checked.
|
|
18
|
-
- **OverCrow**, to run the widget while you write it.
|
|
18
|
+
- **PlayerVox OverCrow**, to run the widget while you write it.
|
|
19
19
|
|
|
20
20
|
`overcrow-widget doctor` tells what your setup has and lacks.
|
|
21
21
|
|
|
@@ -141,8 +141,8 @@ Provide both files or neither, with the same keys. See
|
|
|
141
141
|
overcrow-widget check
|
|
142
142
|
```
|
|
143
143
|
|
|
144
|
-
`check` runs the same validators as OverCrow: manifest, view,
|
|
145
|
-
locales, a lint of the logic against what the VM runs, the project's
|
|
144
|
+
`check` runs the same validators as PlayerVox OverCrow: manifest, view,
|
|
145
|
+
style, locales, a lint of the logic against what the VM runs, the project's
|
|
146
146
|
TypeScript, and a package built in memory and read back. Each problem has a
|
|
147
147
|
stable code, a position and a help line; see
|
|
148
148
|
[diagnostics](cli.md#diagnostics).
|
|
@@ -153,13 +153,13 @@ stable code, a position and a help line; see
|
|
|
153
153
|
overcrow-widget dev
|
|
154
154
|
```
|
|
155
155
|
|
|
156
|
-
`dev` sends the widget to the OverCrow overlay running on your
|
|
157
|
-
reloads it each time you save. OverCrow offers this only when it
|
|
158
|
-
started with development installs allowed
|
|
159
|
-
`overcrow-widget doctor` prints the
|
|
160
|
-
**Unverified · development package** marker;
|
|
161
|
-
granted for the session only, and nothing is
|
|
162
|
-
logic prints in the terminal. See
|
|
156
|
+
`dev` sends the widget to the PlayerVox OverCrow overlay running on your
|
|
157
|
+
machine and reloads it each time you save. OverCrow offers this only when it
|
|
158
|
+
was started with development installs allowed
|
|
159
|
+
(`OVERCROW_WIDGET_DEVELOPMENT=1`; `overcrow-widget doctor` prints the
|
|
160
|
+
commands). The widget shows an **Unverified · development package** marker;
|
|
161
|
+
its declared permissions are granted for the session only, and nothing is
|
|
162
|
+
stored. `log.info(…)` from your logic prints in the terminal. See
|
|
163
163
|
[the development channel](dev-channel.md).
|
|
164
164
|
|
|
165
165
|
## 9. Test it
|
|
@@ -168,9 +168,9 @@ Two kinds of tests, both described in [testing a widget](testing.md):
|
|
|
168
168
|
|
|
169
169
|
- unit tests of the logic with `@overcrow/sdk/testing`, which runs your
|
|
170
170
|
module with virtual time and simulated services;
|
|
171
|
-
- scenarios played by `overcrow-widget test` in OverCrow's
|
|
172
|
-
runtime: the real VM and renderer, services answered by fixtures,
|
|
173
|
-
images compared with references.
|
|
171
|
+
- scenarios played by `overcrow-widget test` in PlayerVox OverCrow's
|
|
172
|
+
headless runtime: the real VM and renderer, services answered by fixtures,
|
|
173
|
+
and images compared with references.
|
|
174
174
|
|
|
175
175
|
<!-- source: templates/counter/tests/example.scenario.json -->
|
|
176
176
|
```json
|
|
@@ -241,7 +241,7 @@ locally stays unverified; users get widgets from the signed catalog. See
|
|
|
241
241
|
|
|
242
242
|
Add a `listing.json` with the marketplace text and run the admission
|
|
243
243
|
yourself. Widgets are no longer proposed by pull request: you will send
|
|
244
|
-
yours from the OverCrow creator space when it opens.
|
|
244
|
+
yours from the PlayerVox OverCrow creator space when it opens.
|
|
245
245
|
|
|
246
246
|
```sh
|
|
247
247
|
overcrow-widget admit
|
|
@@ -6,8 +6,8 @@ its view in markup, style it with a small subset of CSS, and write its logic
|
|
|
6
6
|
in TypeScript against `@overcrow/sdk`. The `overcrow-widget` command-line
|
|
7
7
|
tool checks, tests and packages it; the signed catalog brings it to users.
|
|
8
8
|
|
|
9
|
-
Every built-in widget of OverCrow is written this way, with the
|
|
10
|
-
SDK, package format and sandbox as yours. Their sources are the
|
|
9
|
+
Every built-in widget of PlayerVox OverCrow is written this way, with the
|
|
10
|
+
same public SDK, package format and sandbox as yours. Their sources are the
|
|
11
11
|
[reference widgets](widgets.md).
|
|
12
12
|
|
|
13
13
|
## What a widget is made of
|
|
@@ -52,18 +52,18 @@ export function increment(): void {
|
|
|
52
52
|
|
|
53
53
|
- The logic runs in its own small JavaScript VM, in its own sandboxed
|
|
54
54
|
process. It has no DOM, no file system, no network and no access to other
|
|
55
|
-
widgets; it reaches OverCrow only through the SDK.
|
|
55
|
+
widgets; it reaches PlayerVox OverCrow only through the SDK.
|
|
56
56
|
- After each event, timer tick or service answer, the VM evaluates the view
|
|
57
|
-
again and sends OverCrow only what changed. OverCrow lays out
|
|
58
|
-
the widget itself: no web engine is involved.
|
|
57
|
+
again and sends PlayerVox OverCrow only what changed. OverCrow lays out
|
|
58
|
+
and paints the widget itself: no web engine is involved.
|
|
59
59
|
- Everything that reaches the outside (network, storage, clipboard, game
|
|
60
|
-
data) is a service of OverCrow, which checks the widget's
|
|
61
|
-
consented permissions at each call. See
|
|
60
|
+
data) is a service of PlayerVox OverCrow, which checks the widget's
|
|
61
|
+
declared and consented permissions at each call. See
|
|
62
62
|
[services and permissions](services.md).
|
|
63
63
|
|
|
64
|
-
These pages call OverCrow **the host** when they describe what it
|
|
65
|
-
widget: the host draws the view, answers the services and keeps
|
|
66
|
-
data.
|
|
64
|
+
These pages call PlayerVox OverCrow **the host** when they describe what it
|
|
65
|
+
does for a widget: the host draws the view, answers the services and keeps
|
|
66
|
+
the user's data.
|
|
67
67
|
|
|
68
68
|
## Where to start
|
|
69
69
|
|
|
@@ -74,8 +74,8 @@ data.
|
|
|
74
74
|
[view](view.md), the [style](style.md), the [logic](logic.md),
|
|
75
75
|
[services and permissions](services.md), [forms](forms.md).
|
|
76
76
|
4. Use the tools: the [CLI](cli.md), [tests](testing.md) and the
|
|
77
|
-
[development channel](dev-channel.md) that runs your widget in
|
|
78
|
-
while you write it.
|
|
77
|
+
[development channel](dev-channel.md) that runs your widget in
|
|
78
|
+
PlayerVox OverCrow while you write it.
|
|
79
79
|
5. Look up an element, a style property, a service or an SDK function in the
|
|
80
80
|
[reference](reference.md).
|
|
81
81
|
6. Before you publish, read [the package](package.md),
|
|
@@ -25,12 +25,13 @@ and a way out.
|
|
|
25
25
|
`invalid_request`, a full quota with `quota_exceeded`, and too many
|
|
26
26
|
requests at once with `busy`. See [errors](services.md#errors).
|
|
27
27
|
- **While the logic runs**, exceeding a budget of the VM (the time of a
|
|
28
|
-
turn, the heap, the messages of a turn) stops the widget;
|
|
29
|
-
restarts it a few times. See
|
|
28
|
+
turn, the heap, the messages of a turn) stops the widget;
|
|
29
|
+
PlayerVox OverCrow restarts it a few times. See
|
|
30
30
|
[what happens on a failure](logic.md#what-happens-on-a-failure).
|
|
31
31
|
- **In what the widget shows**, a value out of bounds (a text too long for
|
|
32
|
-
an attribute, too many nodes) is refused by OverCrow and stops
|
|
33
|
-
too: bound what you show, for example the number of rows of a
|
|
32
|
+
an attribute, too many nodes) is refused by PlayerVox OverCrow and stops
|
|
33
|
+
the widget too: bound what you show, for example the number of rows of a
|
|
34
|
+
list.
|
|
34
35
|
|
|
35
36
|
Lengths are logical pixels at 100 % content scale. Text limits count UTF-8
|
|
36
37
|
bytes unless the unit says characters. KiB and MiB are 1024 and 1024²
|
|
@@ -39,13 +39,13 @@ that the view calls with `on:activate={increment}`.
|
|
|
39
39
|
no DOM, `window`, `fetch`, `setTimeout`, `console`, `Intl` or
|
|
40
40
|
`require`. The standard ECMAScript objects are there (`Math`, `JSON`,
|
|
41
41
|
`Date`, `Map`, `Promise`…), and the SDK is the only way out.
|
|
42
|
-
- Everything after that happens in **turns**. OverCrow sends an
|
|
43
|
-
timer tick, a service answer or a change of its own data; your
|
|
44
|
-
then the VM evaluates the view again and sends OverCrow only
|
|
45
|
-
changed. You never update the view by hand.
|
|
42
|
+
- Everything after that happens in **turns**. PlayerVox OverCrow sends an
|
|
43
|
+
event, a timer tick, a service answer or a change of its own data; your
|
|
44
|
+
code runs; then the VM evaluates the view again and sends OverCrow only
|
|
45
|
+
what changed. You never update the view by hand.
|
|
46
46
|
- A turn has a time budget, and the VM a memory ceiling. A widget that
|
|
47
|
-
exceeds one is stopped and restarted by OverCrow, a few times;
|
|
48
|
-
[what happens on a failure](#what-happens-on-a-failure).
|
|
47
|
+
exceeds one is stopped and restarted by PlayerVox OverCrow, a few times;
|
|
48
|
+
see [what happens on a failure](#what-happens-on-a-failure).
|
|
49
49
|
|
|
50
50
|
The only import a logic module may have is `@overcrow/sdk`. Everything else
|
|
51
51
|
it needs is in the module itself.
|
|
@@ -135,8 +135,8 @@ its own.
|
|
|
135
135
|
|
|
136
136
|
## Data from OverCrow: `host`
|
|
137
137
|
|
|
138
|
-
`host` holds what OverCrow knows about the user and the widget.
|
|
139
|
-
always read the latest value.
|
|
138
|
+
`host` holds what PlayerVox OverCrow knows about the user and the widget.
|
|
139
|
+
Its members always read the latest value.
|
|
140
140
|
|
|
141
141
|
| Member | Value |
|
|
142
142
|
| --- | --- |
|
|
@@ -151,11 +151,11 @@ always read the latest value.
|
|
|
151
151
|
| `host.grants` | The capabilities the user granted; read it with `hasGrant`. |
|
|
152
152
|
| `host.messages` | The messages of the active language; read them with `t`. |
|
|
153
153
|
|
|
154
|
-
`onHost(listener)` calls your listener when OverCrow sends new
|
|
155
|
-
the names of the members that changed, before the view is
|
|
156
|
-
Use it when a change needs more than showing the new value:
|
|
157
|
-
subscribe again, redraw a canvas. A member may be sent again
|
|
158
|
-
value: compare it with the one you kept when that matters.
|
|
154
|
+
`onHost(listener)` calls your listener when PlayerVox OverCrow sends new
|
|
155
|
+
values, with the names of the members that changed, before the view is
|
|
156
|
+
evaluated again. Use it when a change needs more than showing the new value:
|
|
157
|
+
re-arm a timer, subscribe again, redraw a canvas. A member may be sent again
|
|
158
|
+
with the same value: compare it with the one you kept when that matters.
|
|
159
159
|
|
|
160
160
|
<!-- source: widgets/stopwatch/logic.ts -->
|
|
161
161
|
```ts
|
|
@@ -173,7 +173,7 @@ through the widget to the game, so the stopwatch hides its buttons unless
|
|
|
173
173
|
## The options menu
|
|
174
174
|
|
|
175
175
|
The rows declared in `wrapper.menu` of the [manifest](manifest.md#the-options-menu)
|
|
176
|
-
are drawn and stored by OverCrow. The logic reads them:
|
|
176
|
+
are drawn and stored by PlayerVox OverCrow. The logic reads them:
|
|
177
177
|
|
|
178
178
|
- `option(id, fallback)` returns the stored value of a toggle, slider or
|
|
179
179
|
choice row, or `fallback` when there is none or it has another type;
|
|
@@ -207,7 +207,7 @@ service: an `action` row can change the state, not write to the clipboard.
|
|
|
207
207
|
|
|
208
208
|
## Timers
|
|
209
209
|
|
|
210
|
-
There is no `setTimeout`. Timers are OverCrow's, through `timers`:
|
|
210
|
+
There is no `setTimeout`. Timers are PlayerVox OverCrow's, through `timers`:
|
|
211
211
|
|
|
212
212
|
| Function | Calls back |
|
|
213
213
|
| --- | --- |
|
|
@@ -225,7 +225,7 @@ timers.every(1000, () => {
|
|
|
225
225
|
});
|
|
226
226
|
```
|
|
227
227
|
|
|
228
|
-
Three rules follow from OverCrow owning the timers:
|
|
228
|
+
Three rules follow from PlayerVox OverCrow owning the timers:
|
|
229
229
|
|
|
230
230
|
- **No timer shorter than 100 ms.** A shorter interval is raised to it.
|
|
231
231
|
Motion belongs to the [style](style.md#transitions-and-animations), not to
|
|
@@ -270,8 +270,8 @@ function start(): void {
|
|
|
270
270
|
```
|
|
271
271
|
|
|
272
272
|
A duration that only has to advance on screen needs no timer at all: the
|
|
273
|
-
`elapsed` element is advanced by OverCrow from a starting point
|
|
274
|
-
gives it. See the [`elapsed` element](elements.md#elapsed).
|
|
273
|
+
`elapsed` element is advanced by PlayerVox OverCrow from a starting point
|
|
274
|
+
the logic gives it. See the [`elapsed` element](elements.md#elapsed).
|
|
275
275
|
|
|
276
276
|
## Time, dates and numbers
|
|
277
277
|
|
|
@@ -339,11 +339,11 @@ export function toggleLabel(running: boolean): string {
|
|
|
339
339
|
}
|
|
340
340
|
```
|
|
341
341
|
|
|
342
|
-
When the user changes OverCrow's language, the view is evaluated
|
|
343
|
-
with the new messages. A text that the logic computed and stored in
|
|
344
|
-
state is not: compute texts in functions the view calls, or refresh them
|
|
345
|
-
`onHost` when `"locale"` changes. The widget's name and its menu labels
|
|
346
|
-
in the manifest, not in the locales.
|
|
342
|
+
When the user changes PlayerVox OverCrow's language, the view is evaluated
|
|
343
|
+
again with the new messages. A text that the logic computed and stored in
|
|
344
|
+
the state is not: compute texts in functions the view calls, or refresh them
|
|
345
|
+
in `onHost` when `"locale"` changes. The widget's name and its menu labels
|
|
346
|
+
are in the manifest, not in the locales.
|
|
347
347
|
|
|
348
348
|
`overcrow-widget check` warns when the view calls `t("key")` with a key
|
|
349
349
|
that has no message, and refuses two files whose keys differ.
|
|
@@ -368,8 +368,8 @@ function paint(): void {
|
|
|
368
368
|
```
|
|
369
369
|
|
|
370
370
|
Coordinates are logical pixels from the top-left corner of the canvas;
|
|
371
|
-
colours are literal (`#rrggbb`) or colour tokens. OverCrow checks
|
|
372
|
-
command and draws them itself: there is no pixel access and no shader.
|
|
371
|
+
colours are literal (`#rrggbb`) or colour tokens. PlayerVox OverCrow checks
|
|
372
|
+
every command and draws them itself: there is no pixel access and no shader.
|
|
373
373
|
Draw again when what you show changes, and when `host.theme` changes if you
|
|
374
374
|
use literal colours.
|
|
375
375
|
|
|
@@ -430,15 +430,17 @@ the SDK replacement:
|
|
|
430
430
|
| `logic.debugger` | `debugger` is a warning. |
|
|
431
431
|
|
|
432
432
|
The lint helps you; it is not what protects the user. The sandbox, the
|
|
433
|
-
VM's budgets and OverCrow's check of everything the widget sends
|
|
433
|
+
VM's budgets and PlayerVox OverCrow's check of everything the widget sends
|
|
434
|
+
do that.
|
|
434
435
|
|
|
435
436
|
## What happens on a failure
|
|
436
437
|
|
|
437
438
|
- An exception in a handler ends that turn; the widget keeps running, and
|
|
438
439
|
`overcrow-widget dev` shows the fault.
|
|
439
440
|
- A turn longer than its budget (50 ms), a heap over its ceiling or too
|
|
440
|
-
many messages in a turn stop the widget. OverCrow shows a fixed
|
|
441
|
-
its frame and restarts it after 1, 5 and 15 seconds, at most
|
|
441
|
+
many messages in a turn stop the widget. PlayerVox OverCrow shows a fixed
|
|
442
|
+
error in its frame and restarts it after 1, 5 and 15 seconds, at most
|
|
443
|
+
three times.
|
|
442
444
|
- A rejected promise of a service call is an ordinary error of your code:
|
|
443
445
|
catch it. See [errors](services.md#errors).
|
|
444
446
|
|
|
@@ -7,7 +7,7 @@ it by hand; it is packaged exactly as written.
|
|
|
7
7
|
|
|
8
8
|
The file is one strict JSON object. A byte-order mark, a duplicate key,
|
|
9
9
|
trailing data or an unknown field rejects it: there is no field that
|
|
10
|
-
OverCrow ignores.
|
|
10
|
+
PlayerVox OverCrow ignores.
|
|
11
11
|
|
|
12
12
|
## A complete example
|
|
13
13
|
|
|
@@ -93,20 +93,21 @@ values it fills in. A manifest with permissions and a menu:
|
|
|
93
93
|
|
|
94
94
|
- **`id`** is the widget's identity everywhere: in the catalog, in the
|
|
95
95
|
user's profile, in its storage. It is `<handle>.<name>`, your publisher
|
|
96
|
-
handle in the OverCrow creator space and a name
|
|
97
|
-
once you verified a domain, that domain reversed
|
|
98
|
-
(`gg.nova.lol-timers`). An ID is final: it is never given to
|
|
99
|
-
widget, even after yours is removed. `nova`, `example`,
|
|
100
|
-
`yourname` are example handles that nobody can publish
|
|
101
|
-
under `com.playervox` are reserved for widgets published by
|
|
96
|
+
handle in the PlayerVox OverCrow creator space and a name
|
|
97
|
+
(`nova.lol-timers`), or, once you verified a domain, that domain reversed
|
|
98
|
+
and a name (`gg.nova.lol-timers`). An ID is final: it is never given to
|
|
99
|
+
another widget, even after yours is removed. `nova`, `example`,
|
|
100
|
+
`yourhandle` and `yourname` are example handles that nobody can publish
|
|
101
|
+
under, and IDs under `com.playervox` are reserved for widgets published by
|
|
102
|
+
PlayerVox.
|
|
102
103
|
- **`version`** is a semantic version. A published version never changes:
|
|
103
104
|
any change to a published widget is a new, higher version.
|
|
104
105
|
- **`schemaVersion`** and **`apiVersion`** are both `1`.
|
|
105
106
|
|
|
106
107
|
### Names
|
|
107
108
|
|
|
108
|
-
`name` gives the name OverCrow shows in its widget list and menus,
|
|
109
|
-
English and in French. Both are required. A name shows as written: no
|
|
109
|
+
`name` gives the name PlayerVox OverCrow shows in its widget list and menus,
|
|
110
|
+
in English and in French. Both are required. A name shows as written: no
|
|
110
111
|
control character and no invisible or text-direction character, such as
|
|
111
112
|
U+200B (zero-width space) or U+202E (right-to-left override). Menu labels
|
|
112
113
|
follow the same rule.
|
|
@@ -121,9 +122,9 @@ follow the same rule.
|
|
|
121
122
|
## Sizes
|
|
122
123
|
|
|
123
124
|
`sizing` says how large the widget is when the user adds it, how small and
|
|
124
|
-
how large the user may resize it, and whether OverCrow can fit its
|
|
125
|
-
its content. Lengths are logical pixels at 100 % scale; the user's
|
|
126
|
-
scale (50 % to 175 %) multiplies them.
|
|
125
|
+
how large the user may resize it, and whether PlayerVox OverCrow can fit its
|
|
126
|
+
frame to its content. Lengths are logical pixels at 100 % scale; the user's
|
|
127
|
+
content scale (50 % to 175 %) multiplies them.
|
|
127
128
|
|
|
128
129
|
<!-- generated:manifest-sizing -->
|
|
129
130
|
| Field | Type | Required | Meaning |
|
|
@@ -145,11 +146,11 @@ Each of `preferred`, `min` and `max` is a pair of dimensions, with
|
|
|
145
146
|
| `height` | integer 1 to 4096 | yes | Logical pixels. |
|
|
146
147
|
<!-- /generated:manifest-dimensions -->
|
|
147
148
|
|
|
148
|
-
With `fit: "both"`, OverCrow sizes the frame to what the view
|
|
149
|
-
both directions: the Clock grows when the user turns the seconds
|
|
150
|
-
`fit: "height"`, the user chooses the width and the height follows
|
|
151
|
-
content. With `fit: "none"`, the frame keeps the size the user gave it
|
|
152
|
-
the view fills it. The user can always resize by hand.
|
|
149
|
+
With `fit: "both"`, PlayerVox OverCrow sizes the frame to what the view
|
|
150
|
+
needs, in both directions: the Clock grows when the user turns the seconds
|
|
151
|
+
on. With `fit: "height"`, the user chooses the width and the height follows
|
|
152
|
+
the content. With `fit: "none"`, the frame keeps the size the user gave it
|
|
153
|
+
and the view fills it. The user can always resize by hand.
|
|
153
154
|
|
|
154
155
|
<!-- source: widgets/clock/manifest.json -->
|
|
155
156
|
```json
|
|
@@ -190,9 +191,9 @@ A network rule is an object of its own; its fields are described with
|
|
|
190
191
|
|
|
191
192
|
## The options menu
|
|
192
193
|
|
|
193
|
-
Every widget has an options menu, opened from its frame. OverCrow
|
|
194
|
-
own rows first: opacity, content size, fit to content and, when the
|
|
195
|
-
needs one, its account. Visibility in Passive mode is the eye in the
|
|
194
|
+
Every widget has an options menu, opened from its frame. PlayerVox OverCrow
|
|
195
|
+
puts its own rows first: opacity, content size, fit to content and, when the
|
|
196
|
+
widget needs one, its account. Visibility in Passive mode is the eye in the
|
|
196
197
|
widget's toolbar, not a menu row. `wrapper.menu` adds yours below them:
|
|
197
198
|
toggles, sliders, choices, actions and groups, each with a label in both
|
|
198
199
|
languages.
|
|
@@ -233,8 +234,8 @@ current value on at most 120 points. Keep labels short, in both languages.
|
|
|
233
234
|
}
|
|
234
235
|
```
|
|
235
236
|
|
|
236
|
-
OverCrow draws the rows, stores their values in the user's profile
|
|
237
|
-
gives them to the logic: read a value with `option(id, fallback)`, and
|
|
237
|
+
PlayerVox OverCrow draws the rows, stores their values in the user's profile
|
|
238
|
+
and gives them to the logic: read a value with `option(id, fallback)`, and
|
|
238
239
|
follow changes with `onHost`. An `action` row has no value: it calls the
|
|
239
240
|
handler you registered with `onMenu`. See
|
|
240
241
|
[the options menu in the logic](logic.md#the-options-menu).
|
|
@@ -346,10 +347,11 @@ Each entry of `choices` is a value and its label:
|
|
|
346
347
|
|
|
347
348
|
`requires` at the top level lists data sources the widget cannot work
|
|
348
349
|
without, with the same names as a row's `requires`. On a machine that lacks
|
|
349
|
-
one, OverCrow neither starts nor shows the widget and keeps its
|
|
350
|
-
layout; the widget comes back when the source does. Use it for
|
|
351
|
-
that has nothing to show otherwise, such as a frame-rate counter
|
|
352
|
-
frame-rate source. For a single optional value, prefer a row's
|
|
350
|
+
one, PlayerVox OverCrow neither starts nor shows the widget and keeps its
|
|
351
|
+
place in the layout; the widget comes back when the source does. Use it for
|
|
352
|
+
a widget that has nothing to show otherwise, such as a frame-rate counter
|
|
353
|
+
without a frame-rate source. For a single optional value, prefer a row's
|
|
354
|
+
`requires`.
|
|
353
355
|
|
|
354
356
|
## A larger memory budget
|
|
355
357
|
|
|
@@ -368,8 +370,8 @@ leaves less room for everything else. Ask for it only when
|
|
|
368
370
|
|
|
369
371
|
## How the manifest is checked
|
|
370
372
|
|
|
371
|
-
`overcrow-widget check` validates the manifest with the validator
|
|
372
|
-
itself runs, and points at the member it refuses:
|
|
373
|
+
`overcrow-widget check` validates the manifest with the validator
|
|
374
|
+
PlayerVox OverCrow itself runs, and points at the member it refuses:
|
|
373
375
|
|
|
374
376
|
```text
|
|
375
377
|
error[manifest.sizing]: `sizing` is out of bounds or inconsistent
|
|
@@ -381,8 +383,8 @@ error[manifest.sizing]: `sizing` is out of bounds or inconsistent
|
|
|
381
383
|
check: 1 error(s), 0 warning(s)
|
|
382
384
|
```
|
|
383
385
|
|
|
384
|
-
OverCrow validates it again when the package is admitted to the
|
|
385
|
-
when it is installed and each time the widget starts. A new version
|
|
386
|
-
manifest asks for more than the previous one (a network rule, a game
|
|
387
|
-
a capability, storage or the clipboard) waits until the user approves
|
|
388
|
-
in the Control Center before it replaces the installed version.
|
|
386
|
+
PlayerVox OverCrow validates it again when the package is admitted to the
|
|
387
|
+
catalog, when it is installed and each time the widget starts. A new version
|
|
388
|
+
whose manifest asks for more than the previous one (a network rule, a game
|
|
389
|
+
event, a capability, storage or the clipboard) waits until the user approves
|
|
390
|
+
it in the Control Center before it replaces the installed version.
|
|
@@ -10,7 +10,7 @@ server installs the OverCrow tools it needs by itself.
|
|
|
10
10
|
claude mcp add overcrow -- npx -y @overcrow/mcp
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
Then ask: "Create
|
|
13
|
+
Then ask: "Create a PlayerVox OverCrow widget that shows…".
|
|
14
14
|
|
|
15
15
|
## Add the server
|
|
16
16
|
|
|
@@ -85,9 +85,9 @@ Developer, Edit Config), then restart Claude Desktop.
|
|
|
85
85
|
|
|
86
86
|
## What the server does
|
|
87
87
|
|
|
88
|
-
- **The first time**, it downloads the OverCrow creator tools of
|
|
89
|
-
computer (the [command-line tool](cli.md) and the runtime that plays
|
|
90
|
-
[tests](testing.md), about 15 MB) from OverCrow's GitHub release. It
|
|
88
|
+
- **The first time**, it downloads the PlayerVox OverCrow creator tools of
|
|
89
|
+
your computer (the [command-line tool](cli.md) and the runtime that plays
|
|
90
|
+
the [tests](testing.md), about 15 MB) from OverCrow's GitHub release. It
|
|
91
91
|
checks every file against the digests written in the server, then keeps
|
|
92
92
|
them in its own folder (`~/.cache/overcrow-mcp`, or
|
|
93
93
|
`%LOCALAPPDATA%\overcrow-mcp` on Windows). Nothing goes on your `PATH`,
|
|
@@ -97,7 +97,7 @@ Developer, Edit Config), then restart Claude Desktop.
|
|
|
97
97
|
(it sees the images that differ), audit, package, prepare the
|
|
98
98
|
submission.
|
|
99
99
|
- **The widget ID** is final. Your assistant asks you for it: your
|
|
100
|
-
publisher handle in the OverCrow creator space and a name
|
|
100
|
+
publisher handle in the PlayerVox OverCrow creator space and a name
|
|
101
101
|
(`nova.lol-timers`), or a domain you can verify
|
|
102
102
|
(`gg.nova.lol-timers`).
|
|
103
103
|
- **The submission**: the server checks everything the creator space asks
|
|
@@ -119,9 +119,9 @@ Developer, Edit Config), then restart Claude Desktop.
|
|
|
119
119
|
## What it does not do
|
|
120
120
|
|
|
121
121
|
- It never sends, signs or publishes anything. You send the ZIP and the
|
|
122
|
-
texts in the OverCrow creator space, at creators.playervox.com.
|
|
123
|
-
- It does not install your widget in OverCrow: trying it in a game
|
|
124
|
-
[development channel](dev-channel.md) of the command-line tool.
|
|
122
|
+
texts in the PlayerVox OverCrow creator space, at creators.playervox.com.
|
|
123
|
+
- It does not install your widget in PlayerVox OverCrow: trying it in a game
|
|
124
|
+
is the [development channel](dev-channel.md) of the command-line tool.
|
|
125
125
|
- It sends nothing about you: no telemetry, no account.
|
|
126
126
|
|
|
127
127
|
## Security
|
|
@@ -129,7 +129,7 @@ Developer, Edit Config), then restart Claude Desktop.
|
|
|
129
129
|
- **Your folders only.** The server works in the folder open in your
|
|
130
130
|
assistant (or the ones given with `--root`). It refuses a system folder,
|
|
131
131
|
your whole home folder, hidden folders, and links that lead outside.
|
|
132
|
-
- **No command of its own choice.** The server runs the OverCrow
|
|
132
|
+
- **No command of its own choice.** The server runs the PlayerVox OverCrow
|
|
133
133
|
command-line tool and npm, nothing else, never through a shell.
|
|
134
134
|
- **Checked downloads.** It downloads only the pinned files from GitHub,
|
|
135
135
|
and checks them before use. npm installs only `@overcrow/sdk` and
|
|
@@ -145,10 +145,10 @@ Developer, Edit Config), then restart Claude Desktop.
|
|
|
145
145
|
## Offline
|
|
146
146
|
|
|
147
147
|
Download `overcrow-creator-tools-VERSION-PLATFORM.zip` of your platform
|
|
148
|
-
from OverCrow's GitHub release once, put it in your widgets
|
|
149
|
-
your assistant to run `setup` with it (`zipPath`). Or start
|
|
150
|
-
`--tools-zip` and the path of the file. The file must be
|
|
151
|
-
the server pins.
|
|
148
|
+
from PlayerVox OverCrow's GitHub release once, put it in your widgets
|
|
149
|
+
folder, and ask your assistant to run `setup` with it (`zipPath`). Or start
|
|
150
|
+
the server with `--tools-zip` and the path of the file. The file must be
|
|
151
|
+
exactly the one the server pins.
|
|
152
152
|
|
|
153
153
|
## Supported computers
|
|
154
154
|
|
|
@@ -61,8 +61,8 @@ names. Two consequences:
|
|
|
61
61
|
- the view itself carries no code: `view.json` refers to the functions of
|
|
62
62
|
`logic.js` by number.
|
|
63
63
|
|
|
64
|
-
A package holds source that OverCrow can read and check, never
|
|
65
|
-
bytecode.
|
|
64
|
+
A package holds source that PlayerVox OverCrow can read and check, never
|
|
65
|
+
compiled bytecode.
|
|
66
66
|
|
|
67
67
|
## The same bytes every time
|
|
68
68
|
|
|
@@ -79,14 +79,14 @@ package` to write it; an archive made with another zip tool is refused.
|
|
|
79
79
|
## The ledger
|
|
80
80
|
|
|
81
81
|
`ledger.json`, written by the tool, lists every other file with its size
|
|
82
|
-
and its SHA-256. OverCrow recomputes it from the archive and
|
|
83
|
-
same bytes. It is what ties each file to the package: a file
|
|
84
|
-
added or removed after packaging no longer matches.
|
|
82
|
+
and its SHA-256. PlayerVox OverCrow recomputes it from the archive and
|
|
83
|
+
requires the same bytes. It is what ties each file to the package: a file
|
|
84
|
+
changed, added or removed after packaging no longer matches.
|
|
85
85
|
|
|
86
86
|
## How OverCrow checks a package
|
|
87
87
|
|
|
88
|
-
OverCrow validates a package in full when it is admitted to the
|
|
89
|
-
when it is installed, and again **each time the widget starts**:
|
|
88
|
+
PlayerVox OverCrow validates a package in full when it is admitted to the
|
|
89
|
+
catalog, when it is installed, and again **each time the widget starts**:
|
|
90
90
|
|
|
91
91
|
1. the size of the archive, its exact layout and the checksum of each
|
|
92
92
|
entry;
|
|
@@ -48,10 +48,11 @@ workflow submits the widget on every version tag:
|
|
|
48
48
|
|
|
49
49
|
<!-- source: docs/content/examples/weather/.github/workflows/submit.yml -->
|
|
50
50
|
```yaml
|
|
51
|
-
# Sends the widget to the OverCrow creator space when a version
|
|
52
|
-
# pushed. The publish key is a secret of the repository, and the
|
|
53
|
-
# release whose creator tools to use is a variable of the
|
|
54
|
-
|
|
51
|
+
# Sends the widget to the PlayerVox OverCrow creator space when a version
|
|
52
|
+
# tag is pushed. The publish key is a secret of the repository, and the
|
|
53
|
+
# OverCrow release whose creator tools to use is a variable of the
|
|
54
|
+
# repository.
|
|
55
|
+
name: Submit to PlayerVox OverCrow
|
|
55
56
|
|
|
56
57
|
on:
|
|
57
58
|
push:
|
|
@@ -76,7 +77,7 @@ jobs:
|
|
|
76
77
|
(cd "$tools" && sha256sum --check --quiet SHA256SUMS)
|
|
77
78
|
install -D -m 755 "$tools"/overcrow-widget-*-linux-x86_64 "$HOME/.local/bin/overcrow-widget"
|
|
78
79
|
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
|
|
79
|
-
- name: Submit to OverCrow
|
|
80
|
+
- name: Submit to PlayerVox OverCrow
|
|
80
81
|
run: overcrow-widget submit --submission submission.json
|
|
81
82
|
env:
|
|
82
83
|
OVERCROW_PUBLISH_KEY: ${{ secrets.OVERCROW_PUBLISH_KEY }}
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Publishing and review
|
|
2
2
|
|
|
3
3
|
> **Pull requests are closed.** Widgets are no longer proposed by pull
|
|
4
|
-
> request: PlayerVox's own widgets already go through the OverCrow
|
|
5
|
-
> space, and yours will when it opens. Until then, this page
|
|
6
|
-
> admission, the review and the catalog a widget goes through.
|
|
4
|
+
> request: PlayerVox's own widgets already go through the PlayerVox OverCrow
|
|
5
|
+
> creator space, and yours will when it opens. Until then, this page
|
|
6
|
+
> describes the admission, the review and the catalog a widget goes through.
|
|
7
7
|
|
|
8
8
|
Widgets reach PlayerVox OverCrow users through the signed widget catalog:
|
|
9
9
|
OverCrow installs only what that catalog lists. This page goes from a
|
|
@@ -86,7 +86,7 @@ overcrow-widget admit widgets/<dir> --format json
|
|
|
86
86
|
your code or `tsc`:
|
|
87
87
|
|
|
88
88
|
1. it builds the directory as `package` does: every source, style, logic
|
|
89
|
-
and package check, then OverCrow's own package reader;
|
|
89
|
+
and package check, then PlayerVox OverCrow's own package reader;
|
|
90
90
|
2. with `--package`, your archive's compiled view must be byte for byte
|
|
91
91
|
what `view.ocml` compiles to;
|
|
92
92
|
3. it checks the schema bounds, the reserved IDs, `listing.json`, the
|
|
@@ -135,14 +135,15 @@ outside CI with the catalog key, whose public half is in
|
|
|
135
135
|
- lists each version with the SHA-256 and the size of its package; a
|
|
136
136
|
published version never changes, and a change is a new version;
|
|
137
137
|
- carries a strictly increasing sequence number and expires after at most
|
|
138
|
-
90 days: OverCrow refuses an older sequence and an expired
|
|
138
|
+
90 days: PlayerVox OverCrow refuses an older sequence and an expired
|
|
139
|
+
catalog;
|
|
139
140
|
- tags PlayerVox reference widgets `built-in` (only `com.playervox.*` IDs):
|
|
140
141
|
they are installed on a new profile with their declared permissions
|
|
141
142
|
granted, except for an update that asks for more.
|
|
142
143
|
|
|
143
|
-
OverCrow verifies the signature, the package digest, its ledger
|
|
144
|
-
compiled view before installing, and again each time it starts the
|
|
145
|
-
See [the package](package.md#how-overcrow-checks-a-package).
|
|
144
|
+
PlayerVox OverCrow verifies the signature, the package digest, its ledger
|
|
145
|
+
and its compiled view before installing, and again each time it starts the
|
|
146
|
+
widget. See [the package](package.md#how-overcrow-checks-a-package).
|
|
146
147
|
|
|
147
148
|
## Updates
|
|
148
149
|
|
|
@@ -26,9 +26,9 @@ together; the pages below are the ones to keep open while you write.
|
|
|
26
26
|
|
|
27
27
|
- The tables of elements, attributes, style properties, tokens, services,
|
|
28
28
|
result shapes and limits are **generated from the widget schema**, the
|
|
29
|
-
same tables that OverCrow and the command-line tool compile into
|
|
30
|
-
validators. A check fails when a page differs from the schema, in
|
|
31
|
-
or in French.
|
|
29
|
+
same tables that PlayerVox OverCrow and the command-line tool compile into
|
|
30
|
+
their validators. A check fails when a page differs from the schema, in
|
|
31
|
+
English or in French.
|
|
32
32
|
- The **SDK types** are generated from the same schema, so a wrong element,
|
|
33
33
|
icon, capability or service parameter is a TypeScript error in your
|
|
34
34
|
logic.
|
|
@@ -48,8 +48,8 @@ These pages describe widget API v1 (`"apiVersion": 1` in the manifest) and
|
|
|
48
48
|
Three specifications, in the public repository, are written for those who
|
|
49
49
|
implement a host or another tool rather than a widget: the complete
|
|
50
50
|
[generated schema reference](../../widget-schema-v1.md), which also covers
|
|
51
|
-
the protocol between OverCrow and the widget's process and the
|
|
52
|
-
payloads; the
|
|
51
|
+
the protocol between PlayerVox OverCrow and the widget's process and the
|
|
52
|
+
catalog's payloads; the
|
|
53
53
|
[wire protocol of the development channel](../../dev-channel.md); and the
|
|
54
54
|
[archive and catalog format](../../widget-package-v1.md). A widget author
|
|
55
55
|
does not need them.
|
|
@@ -36,9 +36,9 @@ the view reads its members:
|
|
|
36
36
|
- A member that goes with `offsetMinutes` is a timestamp to format with
|
|
37
37
|
that UTC offset; see
|
|
38
38
|
[time, dates and numbers](logic.md#time-dates-and-numbers).
|
|
39
|
-
- An `asset:` handle is an image that OverCrow holds for the
|
|
40
|
-
it to the `src` of an `image` or an `avatar`, or draw it on a
|
|
41
|
-
is not a URL and cannot be read as bytes.
|
|
39
|
+
- An `asset:` handle is an image that PlayerVox OverCrow holds for the
|
|
40
|
+
widget: bind it to the `src` of an `image` or an `avatar`, or draw it on a
|
|
41
|
+
canvas. It is not a URL and cannot be read as bytes.
|
|
42
42
|
- A subscription whose shape is "… or `null`" delivers `null` when there is
|
|
43
43
|
nothing to show: no active game, no media player.
|
|
44
44
|
|