@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/docs/en/view.md

@@ -0,0 +1,338 @@
+# The view
+
+`view.ocml` describes what a PlayerVox OverCrow widget shows: a tree of
+elements, bound to the widget's state with `{…}` expressions. It looks like
+HTML or JSX, but it is neither: the set of elements is closed, there is no
+DOM and no script in the view. OverCrow lays out and paints the tree
+itself.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+<box class="checklist">
+  <text class="title">{t("title")}</text>
+  <list class="items" item-height="32">
+    <for each={state.items} as="item" key={item.id}>
+      <box class="row">
+        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
+          <icon name="x"/>
+        </button>
+      </box>
+    </for>
+  </list>
+  <text class="summary">{t("remaining", { count: remaining(state.items) })}</text>
+</box>
+```
+
+This is the checklist template: a title, a scrolling `list` that repeats a
+row per item, and a summary. The logic exports `setDone`, `remove` and
+`remaining`; `t` reads the messages of `locales/`.
+
+The view is compiled when the widget is packaged: `overcrow-widget check`
+reports every mistake with its line and column, and an unknown element,
+attribute or event is an error, never ignored. The source file itself is
+not shipped.
+
+## Markup
+
+- The file is UTF-8, without a byte-order mark.
+- The document is a list of top-level nodes: `<component>` declarations and
+  the children of the widget's root, which is a `box`.
+- Elements are lowercase: `<name …>…</name>` or `<name …/>`.
+- An attribute value is quoted text (`"…"` or `'…'`), an expression
+  (`{…}`), or nothing, which means `true`: `<button submit>`. Attributes
+  are separated by whitespace and never repeated.
+- Comments are `<!-- … -->`, without `--` inside.
+- DOCTYPE, processing instructions, CDATA sections and namespaces are
+  refused.
+
+The entities are `&amp;` `&lt;` `&gt;` `&quot;` `&apos;` `&lbrace;`
+`&rbrace;` `&nbsp;`, and `&#…;` or `&#x…;` for any character that is not a
+control character. A literal `{` or `}` in a quoted value, and a lone `}`
+in text, are refused: write `&lbrace;` and `&rbrace;`.
+
+## Elements
+
+Each element has a fixed content, a set of attributes and the events it can
+send. Containers (`box`, `scroll`, `list`, `form`, `popover`, `button`)
+hold other elements; `text` holds text and inline children; the others are
+leaves that OverCrow draws: `icon`, `image`, `toggle`, `slider`, `field`,
+`chart`, `gauge`…
+
+<!-- generated:element-list -->
+| Element | Meaning |
+| --- | --- |
+| [`box`](elements.md#box) | Generic container; flex or grid layout comes from style. The root of the view is a `box`. |
+| [`scroll`](elements.md#scroll) | Clipping container scrolled by the host with wheel, drag and keyboard. |
+| [`list`](elements.md#list) | Vertical scrolling list whose children are laid out and painted only when visible. |
+| [`text`](elements.md#text) | Block of wrapped text; its inline children flow with it (chat line with emotes). |
+| [`span`](elements.md#span) | Styled run of text inside `text`. |
+| [`icon`](elements.md#icon) | Lucide icon tinted with `color`, sized by `font-size` unless `width` and `height` are set. |
+| [`image`](elements.md#image) | Raster image from the package, or an image handed by a service (an `asset:` handle); `object-fit` applies. |
+| [`avatar`](elements.md#avatar) | Round image with a text fallback while the image is missing or failed. |
+| [`badge`](elements.md#badge) | Short pill of text. |
+| [`button`](elements.md#button) | Activatable control; its children (icon, text) form its content. |
+| [`toggle`](elements.md#toggle) | On/off switch. |
+| [`checkbox`](elements.md#checkbox) | Check control (checklists). |
+| [`slider`](elements.md#slider) | Numeric range control; dragging is handled by the host. |
+| [`select`](elements.md#select) | Drop-down choice; the open list is drawn by the host. |
+| [`option`](elements.md#option) | Choice of a `select`; its text is the visible label. |
+| [`field`](elements.md#field) | Single-line text input edited by the host, input methods (IME) included. |
+| [`textarea`](elements.md#textarea) | Multi-line text input edited by the host, input methods (IME) included. |
+| [`form`](elements.md#form) | Groups named controls. With `intent`, submitting sends their values to a write service directly from the host; the widget's logic never supplies that content. |
+| [`elapsed`](elements.md#elapsed) | Duration text advanced by the host from an anchor given by a service, so a running stopwatch needs no work from the logic. Styled like `text`; repainted only when the shown text changes, at most at 60 Hz, and never while hidden. |
+| [`progress`](elements.md#progress) | Horizontal progress bar. |
+| [`gauge`](elements.md#gauge) | Ring or arc gauge. |
+| [`chart`](elements.md#chart) | Line, area, bar or sparkline chart drawn by the host. |
+| [`series`](elements.md#series) | One data series of a `chart`, coloured with `color`. |
+| [`separator`](elements.md#separator) | Thin rule between groups. |
+| [`canvas`](elements.md#canvas) | Surface painted by the host from the latest list of commands given to `draw`. |
+| [`popover`](elements.md#popover) | Floating panel anchored to an element, drawn above the content and clipped to the widget's frame (drop-downs, context menus). |
+<!-- /generated:element-list -->
+
+[Elements and attributes](elements.md) gives the attributes and events of
+each one.
+
+## Text
+
+Text is allowed only in `text`, `span`, `badge` and `option`. A `text` holds
+either text or inline children (`span`, `icon`, `image`), not both: to
+style one word, put every run in a `span`.
+
+<!-- source: widgets/performance/view.ocml -->
+```xml
+      <text class={row.valueClass} label={row.name} tooltip={row.hint}><span>{row.value}</span><if test={row.unit != ""}><span class="unit">{row.unit}</span></if></text>
+```
+
+Whitespace follows the rule of JSX:
+
+- tabs become spaces;
+- a line break between two words becomes one space;
+- a line break next to a tag or an expression disappears with its
+  indentation;
+- a run of whitespace next to a tag is dropped; one between two expressions
+  on the same line is kept.
+
+So a break before an expression removes the space before it: write
+`you have {state.count} messages` on one line to keep both spaces, or
+write `&#32;` where you need a space that the rule would remove.
+
+## Attributes
+
+A quoted value is converted to the attribute's type and checked when the
+view is compiled:
+
+| Type | Quoted value |
+| --- | --- |
+| boolean | `true` or `false`; the bare attribute means `true` |
+| integer | a decimal integer, without a leading zero |
+| number | a decimal number, without an exponent |
+| number list | numbers separated by spaces: `values="12 18.5 30"` |
+| text, identifier | the text itself |
+| image | a file of the package: `src="assets/logo.png"` |
+
+`attr={expression}` binds the attribute to an expression instead; OverCrow
+checks every value the widget sends. Values that exist only when the widget
+runs, such as an image handed by a service, must be bound.
+
+Five attributes exist on every element:
+
+<!-- generated:common-attributes -->
+| Attribute | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `class` | class list | no | Style classes: distinct names separated by one space. |
+| `ref` | static `ref` name | no | Name by which `draw` designates this `canvas` and by which an attribute such as the `anchor` of a `popover` designates this element. Static, unique in the view, and not allowed inside a `for` or a component body, where it would name several elements. |
+| `label` | text ≤ 256 bytes | no | Accessible name; required on icon-only controls. |
+| `tooltip` | text ≤ 256 bytes | no | Plain text drawn by the host on hover or focus. |
+| `on` | sorted event names | no | Events forwarded to the logic; written `on:<event>` in the view. |
+<!-- /generated:common-attributes -->
+
+`class` is the hook of the [style](style.md). `label` is the accessible
+name of the element: give one to every control whose content is an icon.
+
+### Names for nodes: `ref`
+
+`ref="name"` gives a node a name. Two things use it: `draw(name, commands)`
+paints the `canvas` of that name, and a `popover` is placed against the
+node its `anchor` names.
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+<box ref="panel" class="countdown" on:contextmenu={openMenu}>
+```
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+<popover anchor="panel" placement="pointer" open={state.menu} on:dismiss={closeMenu}>
+  <button class="menu-row" on:activate={resetRounds}>
+    <text class="menu-text">{t("reset-rounds")}</text>
+  </button>
+</popover>
+```
+
+A `ref` is always quoted, unique in the view, and refused inside a `for` or
+a component, where it would name several nodes.
+
+## Events
+
+`on:event={handler}` asks OverCrow to send an event of the element to the
+logic. Without it, the widget does not hear about the event at all: a
+widget is not told about pointer moves or key presses it has not asked for.
+
+A handler is written in one of two ways:
+
+- **the name of a function** exported by the logic, called with the event's
+  detail: `on:activate={increment}`;
+- **a call**, with the arguments you choose; in it, `event` is the event's
+  detail: `on:change={setDone(item.id, event.value)}`.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+        <checkbox label={item.text} checked={item.done} on:change={setDone(item.id, event.value)}/>
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+        <button class="remove" label={t("remove")} on:activate={remove(item.id)}>
+          <icon name="x"/>
+        </button>
+```
+
+The events are `activate`, `contextmenu`, `wheel`, `keydown`, `input`,
+`change`, `submit`, `focus`, `blur`, `reachend`, `stick` and `dismiss`;
+[events](elements.md#events) describes each one and the detail it carries,
+and each [element](elements.md#elements) lists the ones it sends. Some of
+them are user actions, during which a widget may call a protected service;
+see [calls that need a user action](services.md#calls-that-need-a-user-action).
+Widgets receive input only in OverCrow's Interactive mode: in Passive mode,
+clicks go through them to the game.
+
+## Conditions, loops and components
+
+<!-- generated:constructs -->
+| Syntax | Meaning |
+| --- | --- |
+| `{expr}` | Interpolates an expression into text or an attribute value. |
+| `<if test={expr}> … <else-if test={expr}> … <else>` | Conditional subtree. |
+| `<for each={expr} as="item" key={expr}>` | Repeats a subtree; `key` is mandatory and must be unique among siblings. |
+| `<component name="x" props="a b"> … <slot/> … </component>` | Local component with declared properties and one slot, used as `<x a={…}>`. |
+| `on:<event>={handler}` | Subscribes the element to one of its events and names the handler of the logic. |
+<!-- /generated:constructs -->
+
+### `if`, `else-if`, `else`
+
+<!-- source: widgets/stopwatch/view.ocml -->
+```xml
+        <if test={state.stopwatch.running}>
+          <icon name="pause"/>
+        </if>
+        <else>
+          <icon name="play"/>
+        </else>
+```
+
+`else-if` and `else` follow an `if` directly; only whitespace and comments
+may separate them.
+
+### `for`
+
+`for` repeats its children for each item of a list. `each`, `as` and `key`
+are all required, and the key must be unique among the repeated items: it
+is how OverCrow knows which row moved, appeared or went away.
+
+<!-- source: widgets/warframe-market/view.ocml -->
+```xml
+      <for each={state.results} as="item" key={item.slug}>
+        <button class="result" label={item.name} on:activate={select(item.slug)}>
+          <text class="result-name">{item.name}</text>
+          <icon class="result-arrow" name="chevron-right"/>
+        </button>
+      </for>
+```
+
+For a long list, put the `for` in a `list` element: OverCrow lays out and
+paints only the rows that are visible.
+
+### Components
+
+A component is a piece of view with a name and declared properties, to
+write once and use several times. It is local to the view.
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+<component name="stat" props="name value">
+  <box class="stat">
+    <text class="stat-name">{name}</text>
+    <text class="stat-value">{value}</text>
+  </box>
+</component>
+```
+
+<!-- source: docs/content/examples/countdown/view.ocml -->
+```xml
+  <stat name={t("state")} value={stateText(state.running, state.remainingMs)}/>
+```
+
+- Components are declared at the top level, once each, with a name that is
+  not an element's.
+- The body sees only its own properties, not the names around the place
+  where it is used. Pass what it needs.
+- A use passes declared properties only. A quoted property is text; bind
+  it (`value={5}`) for any other type.
+- A body may contain one `<slot/>`, where the children of each use go.
+- A component cannot contain itself, and a use cannot take `on:` handlers:
+  put them on elements inside the body.
+
+`if`, `for` and components are transparent for the content rules: their
+children must suit the element around them.
+
+## Expressions
+
+Expressions are a small, strict subset of JavaScript:
+
+- literals: numbers (`0`, `12`, `1.5`), strings, `true`, `false`, `null`,
+  array and object literals;
+- names in scope and their members: `a.b`, `a?.b`, `a[i]`, `a?.[i]`;
+- operators: `!`, unary `-` and `+`, `* / %`, `+ -`, `< <= > >=`,
+  `== != === !==`, `&&`, `||`, `??`, and `a ? b : c`. `??` cannot be mixed
+  with `&&` or `||` without parentheses;
+- calls of functions exported by the logic, by their bare name:
+  `remaining(state.items)`. `t(key, params)` is one of them.
+
+The names in scope are `state`, the `as` names of the enclosing `for`s, the
+properties of the enclosing component, and `event` in a handler. A name
+cannot hide another one.
+
+There is no assignment, no arrow or function literal, no `new`, `this`,
+template literal, regular expression, method call or global: anything more
+than a simple computation belongs in a function of the logic. This is what
+keeps the view checkable: when a widget is packaged, every expression is
+compiled into a function of `logic.js`, and the view itself carries no
+code.
+
+<!-- source: templates/list/view.ocml -->
+```xml
+        <text class={item.done ? "text done" : "text"}>{item.text}</text>
+```
+
+JavaScript reserved words, `constructor`, `prototype`, `eval`, `undefined`,
+`globalThis`, `overcrow` and any name starting with `__` are refused.
+
+## When the view is wrong
+
+Every problem is a diagnostic of `overcrow-widget check`, with a stable
+code:
+
+| Code | Problem |
+| --- | --- |
+| `view.syntax`, `view.encoding`, `view.size`, `view.invalid_entity` | The file is not well-formed markup. |
+| `view.unknown_element`, `view.invalid_parent` | An element that does not exist, or in a place it cannot be. |
+| `view.unknown_attribute`, `view.duplicate_attribute`, `view.invalid_attribute`, `view.missing_attribute` | An attribute that the element does not have, written twice, with a wrong value, or required and absent. |
+| `view.unknown_event`, `view.invalid_handler` | An event the element does not send (or put on a component use), or a handler that is neither a name nor a call. |
+| `view.expression_syntax`, `view.expression_too_long`, `view.expression_too_deep`, `view.expression_too_many_entries` | An expression outside the subset or its bounds. |
+| `view.reserved_name`, `view.unknown_name` | A refused name, or one that is not in scope. |
+| `view.invalid_text` | Text where the element takes none, or mixed with inline children. |
+| `view.invalid_component`, `view.recursive_component`, `view.invalid_slot`, `view.invalid_construct` | A component, slot, `if` or `for` that breaks its rules. |
+| `view.invalid_ref`, `view.unknown_ref` | A `ref` that is not unique or is inside a `for`, or an `anchor` that names none. |
+| `view.missing_asset` | A static image that is not in `assets/`. |
+| `view.bound_value` | A `value` on a control of a form bound to a write intent; see [forms](forms.md#forms-that-write-user-data). |
+| `view.too_many_elements`, `view.too_many_components`, `view.too_many_children`, `view.too_many_expressions`, `view.too_deep` | A [limit](limits.md) of the view is exceeded. |
+| `logic.missing_export` | The view calls a function that the logic does not export. |

package/dist/content/docs/en/widget-listing.md

@@ -0,0 +1,65 @@
+# The listing: best practices
+
+The listing is what players read in the PlayerVox OverCrow catalog before
+they install a widget: its description, its preview, its category, its
+games, its license and its links. You write it in the creator space, in the
+widget's **Listing** tab.
+
+## Saved as you type
+
+The listing is a draft, saved by itself as you type.
+
+- A widget's first listing goes to review with its first version.
+- Later changes go alone to a quick review: **Submit the listing**. They
+  need no new version of the widget. **Cancel the changes** brings the
+  draft back to the published listing.
+- The category is the exception: you change it at any time, without a
+  review, and the change reaches players with the next publication of the
+  catalog.
+
+## Languages
+
+English comes first: it is the default, shown when a player's language has
+no description. **Add a language** adds another one, 16 languages at most.
+The widget's name comes from its manifest (`name.en`, `name.fr`): to change
+it, change the manifest and submit a version. The languages of the widget's
+own interface come from its `locales/` files.
+
+## Description
+
+- 500 characters at most per language. The first two lines show on the
+  catalog card: say what the widget does, plainly.
+- Say when the widget contacts a server, and which one.
+- No advertising and no claim the widget does not keep.
+
+## Preview image
+
+One image, in English, for every language: a PNG in 4:3, from 480 × 360 to
+1,024 × 768 (1,024 × 768 recommended), 256 KiB at most. Show the widget in
+use, without marketing text.
+
+## Category and games
+
+The category places the widget in the catalog. Add up to five games it is
+made for: players filter the catalog by game.
+
+## License and links
+
+- **License**: "Proprietary, all rights reserved", or an SPDX license such
+  as `MIT` or `Apache-2.0`.
+- **Support**: an e-mail address or a web page where players get help.
+  Required.
+- **Privacy policy**: required as soon as the widget uses the network.
+- **Public source code**: optional; a public repository adds the "Public
+  source code" badge.
+
+Type an address as you know it (`example.com/privacy`): `https://` is added
+for you, and a `/` after a bare domain (`example.com` is saved as
+`https://example.com/`). An address in `http://` is refused.
+
+## From listing.json
+
+A version's sources may carry a `listing.json`, as the command-line tool
+reads it (see [`admit`](cli.md#admit)). In the
+**Listing** tab, **Import listing.json** applies its descriptions, license
+and source code address to the draft.

package/dist/content/docs/en/widget-review.md

@@ -0,0 +1,57 @@
+# Review: types, delays, appeals
+
+Every version of a PlayerVox OverCrow widget, and every change of its
+listing, is read by a person at PlayerVox before players get it. This page
+covers the two kinds of review, their delays, the review thread and the
+appeal. To send a version, see [publish a widget](publish-a-widget.md).
+
+## Quick or full
+
+| Review | When | Longest delay |
+| --- | --- | --- |
+| Full | The first publication, or an update that adds a permission, a network route or a capability | 5 business days |
+| Quick | Any other update, or a change of the listing alone | 2 business days |
+| Appeal | Once per decision, within six months | 7 days |
+| Publication | After the approval | 24 business hours |
+
+Business days run Monday to Friday, except French public holidays. The delay
+is paused while the review waits for your reply or a corrected version.
+A quick review reads the lines that changed since the last approved
+version; a full review reads the whole widget.
+
+## The review thread
+
+Each version in review has a thread in the creator space:
+
+- A **remark** points to a file and a line, quotes the code the reviewer
+  read and cites a numbered rule of the publication rules.
+- You can **reply** to the reviewer. Your reply sends the review back to
+  the reviewer when it was waiting for you.
+- A **corrected version** continues the same thread: send it from
+  **Submit a version**, with a newer version number.
+- The **decision** is approval, changes requested or a refusal, always
+  with its reasons.
+
+Reviewers are shown as "PlayerVox reviewer", never by name. Every time a
+reviewer opens your sources, the creator space shows when, which version
+and why, under **Access to your sources**.
+
+## Appeal
+
+You can contest a refusal or a suspension once per decision, within six
+months, with **Contest the decision**. PlayerVox re-examines the decision
+entirely and answers within 7 days, with its reasons. You can always send a
+new version instead.
+
+## Suspension
+
+When players are at risk (malicious code, a leaked key, a data leak),
+PlayerVox can suspend a widget or a version at once: installed copies are
+turned off. The creator space gives the reason and the rule, and the
+appeal stays open.
+
+## Withdrawal
+
+You can withdraw a version or the whole widget at any time: it leaves the
+catalog at the next publication, and installed copies keep working. A
+version in review or approved but not published yet is withdrawn at once.

package/dist/content/docs/en/widget-statistics.md

@@ -0,0 +1,134 @@
+# Statistics: definitions
+
+The **Statistics** tab of a widget, in the creator space, shows how players
+use it: installs, daily active players, errors and the players' rating.
+PlayerVox OverCrow sends these figures anonymously. They are trends, not
+exact counts: this page says what each figure counts and what it leaves out.
+
+## Where the figures come from
+
+Once a day at most, at a random time, OverCrow sends one anonymous signal
+for each widget installed from the catalog: the widget, its version, the
+day, the system (Windows or Linux), the version of OverCrow, whether the
+widget was shown, installed or uninstalled that day, and its errors (kind,
+place in the code, a rounded count).
+
+- **No identifier**: nothing names the player or the computer, and nothing
+  links the widgets of one player, each widget being sent apart.
+- **No error message**: only the kind of an error and its place in your
+  code. A message may hold personal data.
+- **On by default**: players can turn **Share anonymous statistics** off in
+  OverCrow; nothing is sent after that, and they are no longer counted.
+
+The figures are added up as the signals arrive. **Updated** gives the time
+of the last one counted.
+
+## The figures
+
+| Figure | What it counts |
+| --- | --- |
+| Daily active players | The players who showed the widget at least once that day. The tile gives the mean per day over the period. |
+| Active installs | Installs minus uninstalls, added up since the first signal, never below zero. |
+| Installs · uninstalls | The installs and the uninstalls of the period, and their balance. An update is neither. |
+| Errors | The sum of the errors reported over the period. |
+
+Each tile compares its figure with the period just before, of the same
+length: green when it moves the good way (fewer errors, more players), amber
+the other way, grey when it moves by less than 1 %. **First period** means
+there is nothing before to compare with.
+
+## Periods and filters
+
+- **Period**: 7 days, 28 days, 90 days or 12 months. Over 12 months, the
+  installs and uninstalls chart adds up each week.
+- **Version**: one of your published versions. Active installs show "—"
+  with a version: an installation changes version at every update, so that
+  figure only makes sense for all versions. **Version adoption** compares
+  the versions and does not follow this filter.
+- **System**: Windows or Linux. **Where your widget runs** compares the
+  systems and does not follow this filter.
+- The rating follows no filter.
+
+Every chart has **View as table**, with the same figures day by day.
+
+## Version adoption and where your widget runs
+
+- **Version adoption**: the share of the daily active players on each
+  version. The three newest versions keep their colour; the others add up as
+  **Older**.
+- **Where your widget runs**: the share of active players on Windows and on
+  Linux, and on each version of OverCrow (the two most used, then
+  **Others**).
+
+## Errors
+
+The errors are grouped by kind and by place in your code: the same kind at
+the same line of the same function is one group, whatever the version. The
+table shows the 50 most frequent groups of the period, with their versions,
+their count and their trend; **Export CSV** saves them.
+
+OverCrow reports where an error happened in the package's `logic.js`. The
+creator space traces that position back to your sources (file, line and
+function) with a map of your code built with the package and never
+published.
+
+- **Being traced**: the position is shown as `logic.js:line:column` until it
+  is traced.
+- **Not traced**: the version has no map, or the position is not in it; the
+  raw position stays.
+- **No position in the code**: the widget stopped as a whole (budget
+  exceeded, no answer); see its kind.
+- **SDK**: the error happened inside `@overcrow/sdk`, called from your code.
+
+| Kind | Meaning |
+| --- | --- |
+| `Error` | Error thrown |
+| `TypeError` | Value of an unexpected type |
+| `RangeError` | Value out of range |
+| `ReferenceError` | Unknown name |
+| `SyntaxError` | Invalid syntax |
+| `URIError` | Invalid address encoding |
+| `EvalError` | Code evaluation refused |
+| `AggregateError` | Several errors at once |
+| `InternalError` | Engine limit reached |
+| Thrown value | A value that is not an error was thrown |
+| Memory or processing budget exceeded | The widget was restarted |
+| Stopped responding | The widget was restarted |
+| Failed to load | The code or the view could not load |
+| Widget process stopped | Without reporting a fault |
+| Network request refused | Address not declared in the manifest |
+| Other error | Of a kind the creator space does not know yet |
+
+The kind of an error is the built-in type it was created from, never the
+`name` your code may give it.
+
+## Player rating
+
+Players rate a widget from 0 to 100 in the OverCrow Control Center, with
+their PlayerVox account: one rating per account and per widget, which they
+can change or remove.
+
+- **Score**: the mean of the ratings, rounded, with its rank: S+ from 90,
+  S from 80, A from 70, B from 60, C from 40, D from 20, then F.
+- **From 5 ratings**: below that, the creator space says **Not enough
+  ratings yet** and gives the number of ratings; the catalog shows nothing.
+- **Spread by rank**: the number of ratings in each rank, shown only in
+  the creator space. Nobody sees who rated.
+- **Since the latest version**: the points gained or lost since your latest
+  version was published, when 5 ratings existed before it.
+- The members of your publisher cannot rate its widgets.
+
+Players see the score, the rank and the number of ratings in the catalog
+and on the website.
+
+## Trends, not exact counts
+
+- Only the players who share their anonymous statistics are counted.
+- OverCrow rounds each error count to a step before sending it, and sends
+  at most 10 places in the code per widget and day: the error figures give
+  orders of magnitude.
+- A day is the player's own date.
+- A player who clears OverCrow's data, then installs the widget again,
+  counts as two installs.
+- Signals that look broken or inflated are set aside before they are
+  counted.

package/dist/content/docs/en/widgets.md

@@ -0,0 +1,76 @@
+# Reference widgets
+
+The built-in widgets of PlayerVox OverCrow are ordinary widgets written with
+the public SDK, packaged by `overcrow-widget` and published in the signed
+catalog like yours. Their sources live in
+[`widgets/`](../../../widgets/) of the public repository, under the MIT
+license: read them, copy them, and use them as a starting point.
+
+<!-- generated:widgets -->
+| Widget | Description | ID | Permissions | Source |
+| --- | --- | --- | --- | --- |
+| **Clock** | Shows the local time of day and, optionally, the date, in a 24-hour format. | `com.playervox.overcrow.clock` | none | [widgets/clock/](../../../widgets/clock/) |
+| **FPS** | Shows the game’s presented frame rate, when the host has a frame rate source. | `com.playervox.overcrow.fps` | `fps.read` | [widgets/fps/](../../../widgets/fps/) |
+| **Media** | The track your music player is playing, with its cover, and previous, play/pause and next buttons in Interactive mode. | `com.playervox.overcrow.media` | `media.read`, `media.control` | [widgets/media/](../../../widgets/media/) |
+| **Notes** | Your notes and checklists over the game: up to eight notes, each with free text and a checklist, the same for every game. Read them in Passive mode; in Interactive mode choose, create, delete and edit them in the widget, and tick entries off. They stay on this computer. | `com.playervox.overcrow.notes` | `notes.read`, `notes.write` | [widgets/notes/](../../../widgets/notes/) |
+| **Performance** | Game CPU and memory, plus the temperatures this computer exposes. | `com.playervox.overcrow.performance` | `telemetry.read`, `fps.read` | [widgets/performance/](../../../widgets/performance/) |
+| **Session journal** | The finished play sessions of your game, newest first: date, start time and duration, five per page. Recorded on your device without an account, merged with your PlayerVox journal when you sync. Delete a session after confirmation. | `com.playervox.overcrow.playervox.journal` | `journal.read`, `journal.delete` | [widgets/playervox-journal/](../../../widgets/playervox-journal/) |
+| **My rating** | Your own PlayerVox rating of the Steam game you play: its grade and score, and in Interactive mode three criteria and an optional review to publish or update. Needs your PlayerVox account. | `com.playervox.overcrow.playervox.rating` | `playervox.rating.read`, `playervox.rating.write` | [widgets/playervox-rating/](../../../widgets/playervox-rating/) |
+| **Player reviews** | What PlayerVox players think of the game you play: three reviews per page with each player's grade and score, in your language when a translation exists. Limit them to the players you follow from the widget's menu. Needs your PlayerVox account. | `com.playervox.overcrow.playervox.reviews` | `playervox.reviews.read` | [widgets/playervox-reviews/](../../../widgets/playervox-reviews/) |
+| **PlayerVox score** | The PlayerVox community grade of your Steam game, with its score, rating count and three criteria. No account needed; the badge is always shown. | `com.playervox.overcrow.playervox.score` | `playervox.score.read` | [widgets/playervox-score/](../../../widgets/playervox-score/) |
+| **Session** | Shows how long the current game session has lasted. | `com.playervox.overcrow.session` | `session.read` | [widgets/session/](../../../widgets/session/) |
+| **Manual stopwatch** | A stopwatch to the hundredth of a second, started, paused and reset with its buttons or the host’s shortcuts. | `com.playervox.overcrow.stopwatch` | `stopwatch.read`, `stopwatch.control` | [widgets/stopwatch/](../../../widgets/stopwatch/) |
+| **Twitch chat** | Read and send messages in a public Twitch chat you choose: your favorite channels, the scrolling history with emotes and replies in Interactive mode, the last messages fading out in Passive mode. Needs your Twitch account. | `com.playervox.overcrow.twitch.chat` | `twitch.chat.read`, `twitch.chat.compose` | [widgets/twitch-chat/](../../../widgets/twitch-chat/) |
+| **Warframe Market** | Searches public PC items from a cached catalog, shows an item’s online sellers and buyers in two tabs, and copies a trade whisper when you click. | `com.playervox.overcrow.warframe.market` | `network`, `storage`, `clipboardWrite` | [widgets/warframe-market/](../../../widgets/warframe-market/) |
+<!-- /generated:widgets -->
+
+## What a widget directory holds
+
+- the package sources: `manifest.json`, `view.ocml`, `style.ocss`,
+  `logic.ts`, `locales/`, `LICENSE`;
+- `listing.json`, its marketplace text;
+- `assets/preview.png`, its marketplace preview: the image of its `preview`
+  scenario, framed and staged by `node scripts/compose-previews.mjs`;
+- `tests/`: unit tests of the logic, and scenarios with reference images in
+  both themes, both languages and two scales, played by
+  `overcrow-widget test` in OverCrow's headless runtime;
+- `README.md`: what it shows, its menu, its permissions, how it works and
+  what it costs.
+
+## What each one shows
+
+| To see how to… | Read |
+| --- | --- |
+| tick at each minute or second of local time, follow a menu option | Clock |
+| subscribe to a service and show a missing value | FPS, Session |
+| lay out a list of values in a grid, hide a menu row the machine cannot serve | Performance |
+| show an image handed by OverCrow, retry a subscription that ended | Media |
+| command a service on a user action, let OverCrow advance a duration | Manual stopwatch |
+| edit text through a form bound to a write intent, keep drafts | Notes, My rating |
+| draw on a canvas | PlayerVox score, My rating |
+| page through a service and react to a revision | Player reviews, Session journal |
+| keep a long scrolling list at its end, send a message | Twitch chat |
+| call an HTTP API, cache it in storage, copy to the clipboard | Warframe Market |
+
+Warframe Market is not a built-in: a PlayerVox widget of the catalog,
+installed on request, it shows network routes with a declared response
+bound, storage for a cached catalog and a clipboard copy on a click.
+
+## Work on one
+
+From a checkout of the repository, link the SDK of that revision into the
+widgets, then check one, package it and run its unit tests:
+
+```sh
+node scripts/prepare-widgets.mjs
+overcrow-widget check widgets/clock
+overcrow-widget package widgets/clock
+node --test widgets/clock/tests/logic.test.mjs
+```
+
+`prepare-widgets.mjs` needs the SDK built first (`npm ci` then
+`npm run build` in `sdk/`). The four templates of `overcrow-widget init`
+are in [`templates/`](../../../templates/), and two complete examples
+written for these pages in
+[`docs/content/examples/`](../examples/): `weather` calls an HTTP API and
+`countdown` uses a timer, a canvas, a context menu and storage.