@overcrow/mcp 0.0.0 → 0.1.1

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

@@ -0,0 +1,241 @@
+# Limits
+
+Everything in a PlayerVox OverCrow widget is bounded: the size of its
+files, the number of elements of its view, the time of a turn of its logic,
+the bytes of a response. The bounds keep a widget small and keep one widget
+from slowing the game or the others. This page lists the ones a widget
+author meets.
+
+```text
+error[view.too_many_children]: the view exceeds a size bound of the schema
+  --> view.ocml:15:14375
+   = help: split long static content, or render repeated content with <for>
+check: 1 error(s), 0 warning(s)
+```
+
+An element with more than 1024 children: `check` names the bound, the place
+and a way out.
+
+## What happens at a limit
+
+- **In the project's files**, a limit is an error of `overcrow-widget
+  check`, with a code that names it (`view.too_many_elements`,
+  `style.too_many_rules`, `project.file_size`…). Nothing is truncated.
+- **In a service call**, a parameter out of bounds fails with
+  `invalid_request`, a full quota with `quota_exceeded`, and too many
+  requests at once with `busy`. See [errors](services.md#errors).
+- **While the logic runs**, exceeding a budget of the VM (the time of a
+  turn, the heap, the messages of a turn) stops the widget; OverCrow
+  restarts it a few times. See
+  [what happens on a failure](logic.md#what-happens-on-a-failure).
+- **In what the widget shows**, a value out of bounds (a text too long for
+  an attribute, too many nodes) is refused by OverCrow and stops the widget
+  too: bound what you show, for example the number of rows of a list.
+
+Lengths are logical pixels at 100 % content scale. Text limits count UTF-8
+bytes unless the unit says characters. KiB and MiB are 1024 and 1024²
+bytes. The limits that the logic can read are also constants of the SDK:
+see [limit constants](sdk.md#limit-constants).
+
+## Limits by topic
+
+<!-- generated:limits -->
+### Project files and package
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_VIEW_SOURCE_BYTES` | 256 KiB | `view.ocml` source size. |
+| `MAX_STYLE_SOURCE_BYTES` | 128 KiB | `style.ocss` source size. |
+| `MAX_LOGIC_BYTES` | 512 KiB | The `logic.js` script, compiled code of the view included. |
+| `MAX_LOCALE_ENTRIES` | 2048 | Messages in one `locales/<locale>.json` file. |
+| `MAX_LOCALE_KEY_BYTES` | 128 bytes | Length of one message key. |
+| `MAX_LOCALE_VALUE_BYTES` | 4 KiB | Length of one message text. |
+| `MAX_LOCALE_FILE_BYTES` | 256 KiB | One `locales/<locale>.json` file. |
+| `MAX_MANIFEST_BYTES` | 64 KiB | `manifest.json` size. |
+| `MAX_LICENSE_BYTES` | 64 KiB | `LICENSE` text. |
+| `MAX_COMPILED_VIEW_BYTES` | 512 KiB | `view.json`, the compiled view. |
+| `MAX_PACKAGE_BYTES` | 16 MiB | Size of one `.ocpkg` archive. |
+| `MAX_PACKAGE_FILES` | 256 | Entries in one archive, `manifest.json` and `ledger.json` included. |
+| `MAX_PACKAGE_PATH_BYTES` | 128 bytes | Path of one archive entry. |
+| `MAX_ASSET_PATH_SEGMENTS` | 4 | Path segments below `assets/`, the file name included. |
+
+### Manifest and options menu
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MIN_WIDGET_ID_BYTES` | 3 bytes | Shortest widget ID. |
+| `MAX_WIDGET_ID_BYTES` | 128 bytes | Longest widget ID; each dot-separated segment is at most 63 bytes. |
+| `MAX_VERSION_BYTES` | 64 bytes | Package version text. |
+| `MAX_WIDGET_NAME_CHARS` | 48 characters | One English or French widget name in the manifest. |
+| `MAX_WIDGET_EDGE_PX` | 4096 px | Width or height of a widget's frame. |
+| `MIN_CONTENT_SCALE` | 500 ‰ | Smallest content scale (50 %). |
+| `MAX_CONTENT_SCALE` | 1750 ‰ | Largest content scale (175 %). |
+| `MAX_GAME_EVENTS` | 32 | Semantic game events declared by one package. |
+| `MAX_MENU_ROWS` | 16 | Widget rows in `wrapper.menu`, group rows and their children included. |
+| `MAX_MENU_DEPTH` | 1 | Submenu levels: a `group` cannot contain another `group`. |
+| `MAX_MENU_LABEL_CHARS` | 80 characters | One English or French label of a row or choice. |
+| `MAX_MENU_ID_BYTES` | 48 bytes | Row ID and choice value. |
+| `MIN_MENU_CHOICES` | 2 | Choices of one `choice` row, lower bound. |
+| `MAX_MENU_CHOICES` | 16 | Choices of one `choice` row, upper bound. |
+| `MAX_MENU_NUMBER` | 1000000 absolute value | Absolute value of a slider bound, step or default. |
+| `MAX_SLIDER_STEPS` | 10000 | `(max - min) / step` of one slider row. |
+
+### Network rules
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_NETWORK_RULES` | 32 | Network rules declared by one package. |
+| `MAX_NETWORK_PATH_BYTES` | 1 KiB | `path` template of one network rule. |
+| `MAX_PATH_PARAMS` | 8 | `pathParams` of one network rule. |
+| `MAX_QUERY_PARAMS` | 16 | `queryParams` of one network rule. |
+| `MAX_ENUM_VALUES` | 32 | Values of one `enum` parameter constraint. |
+| `MAX_ENUM_VALUE_BYTES` | 128 bytes | One `enum` parameter value. |
+| `MAX_PARAMETER_NAME_BYTES` | 32 bytes | Name of one path or query parameter. |
+| `MAX_SLUG_PARAMETER_BYTES` | 128 bytes | Largest `maxLength` of a `slug` parameter constraint. |
+| `MAX_STRING_PARAMETER_BYTES` | 256 bytes | Largest `maxLength` of a `string` query parameter constraint. |
+| `MAX_DNS_LABEL_BYTES` | 63 bytes | One dot-separated label of a network origin host or of a widget ID. |
+| `MAX_DNS_NAME_BYTES` | 253 bytes | Host name of one network origin. |
+| `MAX_REQUEST_URL_BYTES` | 2 KiB | URL text of one request. |
+| `MAX_HTTP_REQUEST_BYTES` | 256 KiB | Body of one outgoing request. |
+| `MAX_HTTP_RESPONSE_BYTES` | 1 MiB | Body of one response delivered to the widget when its network rule declares no `maxResponseBytes`, and of every `as: "image"` response. |
+| `MAX_HTTP_DECLARED_RESPONSE_BYTES` | 3 MiB | Largest `maxResponseBytes` of one network rule: the body of one response the rule allows, delivered to the widget. |
+| `MAX_HTTP_RESPONSE_BYTES_PER_WIDGET` | 4 MiB | Response bytes one widget's requests in flight may reserve, each the bound of its rule; `busy` beyond. Equals `MAX_HTTP_CONCURRENT_PER_WIDGET` × `MAX_HTTP_RESPONSE_BYTES`, so rules without `maxResponseBytes` never reach it. |
+| `MAX_HTTP_RESPONSE_BYTES_GLOBAL` | 64 MiB | Response bytes all widgets' requests in flight may reserve; `busy` beyond. Equals `MAX_HTTP_CONCURRENT_GLOBAL` × `MAX_HTTP_RESPONSE_BYTES`. |
+| `MAX_HTTP_CONCURRENT_PER_WIDGET` | 4 | Requests in flight for one widget. |
+| `MAX_HTTP_CONCURRENT_GLOBAL` | 64 | Requests in flight for all widgets. |
+| `HTTP_TIMEOUT_MS` | 30000 ms | Total duration of one request. |
+
+### Listing
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_LISTING_LOCALIZATIONS` | 16 | Localized texts of one listing. |
+| `MAX_LISTING_NAME_BYTES` | 128 bytes | Marketplace name of one localization. |
+| `MAX_LISTING_DESCRIPTION_BYTES` | 512 bytes | Marketplace description of one localization. |
+| `MAX_AUTHOR_BYTES` | 128 bytes | Author shown in a listing. |
+| `MAX_SPDX_LICENSE_BYTES` | 64 bytes | SPDX license expression of a listing. |
+| `MAX_CATALOG_URL_BYTES` | 2 KiB | Source URL of a listing. |
+| `MAX_PREVIEW_BYTES` | 256 KiB | PNG preview image of a listing. |
+
+### View
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_VIEW_ELEMENTS` | 4096 | Elements written in `view.ocml`, components included. |
+| `MAX_COMPONENTS` | 64 | Local components declared in one view. |
+| `MAX_COMPONENT_PROPS` | 32 | Declared properties of one local component. |
+| `MAX_VIEW_EXPRESSIONS` | 4096 | Compiled expressions of one view, handlers included. |
+| `MAX_EXPRESSION_BYTES` | 1 KiB | Source length of one `{expr}` expression. |
+| `MAX_EXPRESSION_DEPTH` | 32 | Nesting of operators, calls, members and literals in one expression. |
+| `MAX_CALL_ARGUMENTS` | 8 | Arguments of one call, and entries of one object or array literal, in an expression. |
+| `MAX_SCENE_NODES` | 4096 | Elements present in the view of a running widget, list items included. |
+| `MAX_TREE_DEPTH` | 32 | Depth of the view's tree below its root, also the nesting limit of `if`, `for` and components. |
+| `MAX_CHILDREN` | 1024 | Children of one element. |
+| `MAX_NODE_TEXT_BYTES` | 16 KiB | Text content of one `text`, `span`, `badge` or `option` element. |
+| `MAX_ATTRIBUTE_TEXT_BYTES` | 1 KiB | Any text attribute not bounded more tightly. |
+| `MAX_LABEL_BYTES` | 256 bytes | `label`, `tooltip` and `placeholder` attributes. |
+| `MAX_IDENTIFIER_BYTES` | 64 bytes | Class names, component names, field names, `@keyframes` names and similar identifiers. |
+| `MAX_INITIALS_BYTES` | 16 bytes | `initials` fallback of an `avatar`. |
+| `MAX_CLASSES_PER_NODE` | 16 | Classes on one element. |
+| `MAX_FIELD_TEXT_BYTES` | 16 KiB | Content of one `field` or `textarea`, and of one `input` or `change` event. |
+| `MAX_CHART_POINTS` | 1024 | Values in one chart series. |
+| `MAX_CHART_SERIES` | 4 | `series` children of one `chart`. |
+| `MAX_KEY_BYTES` | 32 bytes | `key` of one `keydown` event: one printable character or a named key. |
+
+### Style
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_STYLE_RULES` | 1024 | Rules in one style sheet, `@keyframes` blocks excluded. |
+| `MAX_SELECTORS_PER_RULE` | 8 | Comma-separated selectors of one rule. |
+| `MAX_COMPOUNDS_PER_SELECTOR` | 4 | Compound selectors joined by combinators in one selector. |
+| `MAX_SIMPLE_SELECTORS_PER_COMPOUND` | 6 | Type, class and state selectors in one compound selector. |
+| `MAX_DECLARATIONS_PER_RULE` | 64 | Declarations in one rule or `@keyframes` stop. |
+| `MAX_KEYFRAMES` | 32 | `@keyframes` blocks in one style sheet. |
+| `MAX_KEYFRAME_STOPS` | 16 | Stops in one `@keyframes` block. |
+| `MAX_SHADOWS` | 2 | Layers in one `box-shadow` value. |
+| `MAX_SHADOW_BLUR_PX` | 64 px | Blur and spread radius of one shadow. |
+| `MAX_GRADIENT_STOPS` | 8 | Colour stops in one `linear-gradient()`. |
+| `MAX_GRID_TRACKS` | 24 | Tracks in one `grid-template-rows` or `grid-template-columns`. |
+| `MAX_GRID_FRACTION` | 1000 absolute value | Largest `<fr>` factor of one grid track. |
+| `MAX_TRANSITIONS` | 8 | Entries in one `transition` or `animation` list. |
+| `MAX_ANIMATION_MS` | 300000 ms | Duration or delay of one transition or animation. |
+| `MAX_ACTIVE_ANIMATIONS` | 64 | Transitions and animations running at once in one widget; extra ones jump to their end state. |
+| `ANIMATION_RATE_HZ` | 60 Hz | Maximum repaint rate while an animation runs; nothing repaints when nothing changes. |
+| `MAX_LENGTH_PX` | 16384 px | Absolute value of any length, offset or coordinate. |
+| `MIN_FONT_SIZE_PX` | 6 px | Smallest `font-size` before content scale. |
+| `MAX_FONT_SIZE_PX` | 96 px | Largest `font-size` before content scale. |
+| `MAX_PERCENT` | 1000 absolute value | Absolute value of any `<percent>` in a style value. |
+| `MAX_ANGLE_DEG` | 3600 absolute value | Absolute value of any `<angle>`, in degrees (ten turns). |
+| `MAX_TRANSFORM_FUNCTIONS` | 4 | Functions in one `transform` value. |
+| `MAX_TRANSFORM_SCALE` | 8 absolute value | Largest `scale()` factor; the smallest is 0. |
+| `MAX_EASING_STEPS` | 60 | Steps of one `steps()` easing. |
+| `MAX_ANIMATION_ITERATIONS` | 10000 | Finite iteration count of one animation; `infinite` stays allowed. |
+
+### Drawing and images
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_CANVASES` | 8 | `canvas` elements in one widget. |
+| `MAX_DRAW_COMMANDS` | 4096 | Commands in one call of `draw`, replacing the canvas content. |
+| `MAX_PATH_POINTS` | 16384 | Vertices the host draws for one call of `draw`, all paths included, counted with a fixed ceiling per command: `moveTo` and `lineTo` 1, `quadTo` 8, `cubicTo` 16, `arc` and `circle` 64, `rect` 36, other commands 0. |
+| `MAX_DRAW_STATE_DEPTH` | 16 | Nested `save` commands. |
+| `MAX_IMAGE_EDGE_PX` | 2048 px | Width or height of one decoded image. |
+| `MAX_IMAGE_ENCODED_BYTES` | 2 MiB | Encoded size of one PNG, JPEG or WebP image before decoding. |
+
+### Logic
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `VM_HEAP_BYTES` | 16 MiB | Heap ceiling of the VM when the manifest requests none. |
+| `VM_MAX_HEAP_BYTES` | 48 MiB | Largest heap ceiling a manifest may request. |
+| `VM_STACK_BYTES` | 256 KiB | Stack ceiling of the VM. |
+| `VM_PROCESS_MEMORY_BYTES` | 64 MiB | Hard memory ceiling of one widget's process. |
+| `VM_CPU_PERCENT` | 25 % of one core | CPU ceiling of one widget's process. |
+| `VM_TURN_BUDGET_MS` | 50 ms | Wall time of one turn of the logic before the VM interrupts it. |
+| `VM_JOBS_PER_TURN` | 1024 | Promise jobs run in one turn; a longer queue is a resource failure. |
+| `VM_MESSAGES_PER_TURN` | 64 | Messages the widget may emit during one turn. |
+| `MAX_VM_MESSAGES_PER_SECOND` | 120 per second | Sustained rate of messages from the widget to the host. |
+| `MAX_VM_MESSAGE_BURST` | 240 | Burst of messages allowed above that rate. |
+| `MAX_PATCH_BYTES` | 256 KiB | Size of what the widget sends at once: one change of the view or one call of `draw`. |
+| `MAX_PATCH_OPS` | 4096 | Operations in one change of the view (elements created, removed, moved or changed) after a turn. |
+| `MAX_TIMERS` | 16 | Active timers of one widget. |
+| `MIN_TIMER_INTERVAL_MS` | 100 ms | Shortest timer period; animation belongs to style, not to timers. |
+| `CLOCK_RESOLUTION_MS` | 1 ms | Granularity of `Date.now()` inside the VM. |
+| `MAX_LOG_BYTES` | 4 KiB | Text of one `log` call. |
+
+### Services
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_SERVICE_CALLS_IN_FLIGHT` | 16 | Unanswered service calls of one widget, subscriptions excluded. |
+| `MAX_SUBSCRIPTIONS` | 16 | Open service subscriptions of one widget. |
+| `STORAGE_QUOTA_BYTES` | 256 KiB | Keys and values stored by one widget. |
+| `MAX_STORAGE_KEYS` | 512 | Keys stored by one widget. |
+| `MAX_STORAGE_KEY_BYTES` | 128 bytes | Length of one storage key. |
+| `MAX_STORAGE_VALUE_BYTES` | 64 KiB | Serialized JSON size of one storage value. |
+| `MAX_CLIPBOARD_BYTES` | 16 KiB | Text of one clipboard write. |
+| `MAX_OBJECT_ID_BYTES` | 128 bytes | Opaque object ID or cursor exchanged with a capability service. |
+
+### Notes, reviews and chat
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `MAX_NOTES` | 8 | Notes in the user's notes document; `notes.create` fails beyond it. |
+| `MAX_NOTE_TITLE_BYTES` | 96 bytes | Note title, non-empty after trimming. |
+| `MAX_NOTE_BODY_BYTES` | 8 KiB | Note body. |
+| `MAX_NOTE_ITEMS` | 64 | Checklist items of one note. |
+| `MAX_NOTE_ITEM_BYTES` | 256 bytes | One checklist item. |
+| `MAX_REVIEW_CHARS` | 2000 characters | PlayerVox review text. |
+| `MAX_CHAT_MESSAGE_CHARS` | 500 characters | Twitch chat message, the Twitch limit; not empty or whitespace-only, no control characters. |
+| `MAX_CHAT_FRAGMENTS` | 16 | Text and emote runs of one delivered chat message; the host merges the rest into text. |
+| `MAX_CHAT_FAVORITES` | 20 | Favourite Twitch channels kept by the host. |
+| `MAX_CHAT_CHANNEL_BYTES` | 25 bytes | Twitch channel login after normalization: ASCII letters, digits and `_`, lowercased. |
+
+### Reference images
+
+| Limit | Value | Meaning |
+| --- | --- | --- |
+| `PARITY_CHANNEL_TOLERANCE` | 2 levels of 255 | Largest per-channel difference for a pixel to count as equal to the reference image's. |
+| `PARITY_MAX_DIFFERENT_PIXELS` | 100 ppm | Share of pixels allowed beyond the channel tolerance. One wrong 10 px letter in a 360 × 260 widget is 385 ppm. |
+<!-- /generated:limits -->

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

@@ -0,0 +1,446 @@
+# The logic
+
+`logic.ts` is the code of a PlayerVox OverCrow widget: it owns the widget's
+state, exports the functions the view calls, and talks to OverCrow through
+`@overcrow/sdk`. It is one TypeScript (or JavaScript) module, bundled with
+the SDK into the package's only script, `logic.js`.
+
+<!-- source: templates/counter/logic.ts -->
+```ts
+// A counter. The view reads `state.count` and calls `increment` and
+// `decrement` on activation; after each handler the VM renders the view
+// again and sends only what changed.
+import { initState } from "@overcrow/sdk";
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    count: number;
+  }
+}
+
+const state = initState({ count: 0 });
+
+export function increment(): void {
+  state.count += 1;
+}
+
+export function decrement(): void {
+  state.count -= 1;
+}
+```
+
+That is a complete logic module: a state with one member, and two handlers
+that the view calls with `on:activate={increment}`.
+
+## How the logic runs
+
+- The module runs once, when the widget starts, in its own JavaScript VM
+  inside a sandboxed process. It is not a browser and not Node.js: there is
+  no DOM, `window`, `fetch`, `setTimeout`, `console`, `Intl` or
+  `require`. The standard ECMAScript objects are there (`Math`, `JSON`,
+  `Date`, `Map`, `Promise`…), and the SDK is the only way out.
+- Everything after that happens in **turns**. OverCrow sends an event, a
+  timer tick, a service answer or a change of its own data; your code runs;
+  then the VM evaluates the view again and sends OverCrow only what
+  changed. You never update the view by hand.
+- A turn has a time budget, and the VM a memory ceiling. A widget that
+  exceeds one is stopped and restarted by OverCrow, a few times; see
+  [what happens on a failure](#what-happens-on-a-failure).
+
+The only import a logic module may have is `@overcrow/sdk`. Everything else
+it needs is in the module itself.
+
+## The state
+
+`state` is a plain object. Declare the type of its members once, by
+extending the SDK's `WidgetState` interface, give it its first value with
+`initState`, and assign to it from then on.
+
+<!-- source: templates/list/logic.ts -->
+```ts
+interface Item {
+  id: number;
+  text: string;
+  done: boolean;
+}
+
+declare module "@overcrow/sdk" {
+  interface WidgetState {
+    items: Item[];
+  }
+}
+
+const state = initState({
+  items: [
+    { id: 1, text: t("first"), done: false },
+    { id: 2, text: t("second"), done: false },
+    { id: 3, text: t("third"), done: true },
+  ] as Item[],
+});
+```
+
+After each turn the VM evaluates the whole view again and sends the
+differences. There is nothing to subscribe to and no setter to call:
+changing a member in place and replacing it both work.
+
+<!-- source: templates/list/logic.ts -->
+```ts
+export function setDone(id: number, done: unknown): void {
+  state.items = state.items.map((item) => (item.id === id ? { ...item, done: done === true } : item));
+}
+```
+
+Keep in the state what the view shows, and in ordinary variables what only
+the logic needs (a timer, a subscription). A value in the state must be
+plain data: numbers, strings, booleans, `null`, arrays and objects of
+those.
+
+## Functions for the view
+
+The view can call only what the logic module exports by name:
+
+- in an **expression**, a function that returns what to show:
+  `{remaining(state.items)}`;
+- as a **handler**, a function that changes the state:
+  `on:activate={remove(item.id)}`.
+
+<!-- source: templates/list/logic.ts -->
+```ts
+export function remove(id: number): void {
+  state.items = state.items.filter((item) => item.id !== id);
+}
+```
+
+<!-- source: templates/list/logic.ts -->
+```ts
+export function remaining(items: readonly Item[]): number {
+  return items.filter((item) => !item.done).length;
+}
+```
+
+Expression functions run every time the view is evaluated: keep them cheap
+and without side effects. A handler named without arguments
+(`on:change={setRepeat}`) receives the event's detail:
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+export function setRepeat(event: { value: unknown }): void {
+  state.repeat = event.value === true;
+}
+```
+
+`export default` is refused: the view calls named exports. `t` needs no
+export: a view that calls `t(…)` gets the SDK's, unless the logic exports
+its own.
+
+## Data from OverCrow: `host`
+
+`host` holds what OverCrow knows about the user and the widget. Its members
+always read the latest value.
+
+| Member | Value |
+| --- | --- |
+| `host.locale` | Interface language, `"en"` or `"fr"`. |
+| `host.theme` | `"dark"` or `"light"`. |
+| `host.mode` | `"passive"` or `"interactive"`: the widget receives input only in Interactive mode. |
+| `host.visible` | Whether the widget is shown. |
+| `host.scale` | Content scale in thousandths: `1000` is 100 %. |
+| `host.viewport` | `{ width, height }` of the widget's content, in logical pixels. |
+| `host.region` | The user's regional formats and UTC offset; the formatting helpers read it. |
+| `host.options` | Values of the options menu; read them with `option`. |
+| `host.grants` | The capabilities the user granted; read it with `hasGrant`. |
+| `host.messages` | The messages of the active language; read them with `t`. |
+
+`onHost(listener)` calls your listener when OverCrow sends new values, with
+the names of the members that changed, before the view is evaluated again.
+Use it when a change needs more than showing the new value: re-arm a timer,
+subscribe again, redraw a canvas. A member may be sent again with the same
+value: compare it with the one you kept when that matters.
+
+<!-- source: widgets/stopwatch/logic.ts -->
+```ts
+onHost((changed) => {
+  if (changed.includes("mode")) {
+    state.interactive = host.mode === "interactive";
+  }
+});
+```
+
+Most widgets only show the buttons that work: in Passive mode a click goes
+through the widget to the game, so the stopwatch hides its buttons unless
+`host.mode` is `"interactive"`.
+
+## The options menu
+
+The rows declared in `wrapper.menu` of the [manifest](manifest.md#the-options-menu)
+are drawn and stored by OverCrow. The logic reads them:
+
+- `option(id, fallback)` returns the stored value of a toggle, slider or
+  choice row, or `fallback` when there is none or it has another type;
+- `onHost` reports `"options"` when the user changes a row;
+- `onMenu(handler)` receives the ID of an `action` row when the user
+  chooses it.
+
+<!-- source: widgets/clock/logic.ts -->
+```ts
+export function menuValues(): { seconds: boolean; showDate: boolean; order: DateOrder } {
+  return {
+    seconds: option("show-seconds", false),
+    showDate: option("show-date", true),
+    order: DATE_ORDERS[option("date-format", "day-month-year")] ?? "dmy",
+  };
+}
+```
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+onMenu((row) => {
+  if (row === "reset-rounds") {
+    resetRounds();
+  }
+});
+```
+
+Choosing a menu row is not a
+[user action](services.md#calls-that-need-a-user-action) for a protected
+service: an `action` row can change the state, not write to the clipboard.
+
+## Timers
+
+There is no `setTimeout`. Timers are OverCrow's, through `timers`:
+
+| Function | Calls back |
+| --- | --- |
+| `timers.after(ms, callback)` | once, after `ms` |
+| `timers.every(ms, callback)` | every `ms` |
+| `timers.atEach(unit, callback)` | at each `"second"`, `"minute"`, `"hour"` or `"day"` of the user's local time |
+
+Each returns a `Timer` with `cancel()`.
+
+<!-- source: templates/chart/logic.ts -->
+```ts
+timers.every(1000, () => {
+  const previous = state.values.at(-1) ?? 50;
+  state.values = [...state.values.slice(1 - POINTS), sample(previous)];
+});
+```
+
+Three rules follow from OverCrow owning the timers:
+
+- **No timer shorter than 100 ms.** A shorter interval is raised to it.
+  Motion belongs to the [style](style.md#transitions-and-animations), not to
+  timers.
+- **A hidden widget does not tick.** A repeating timer skips the ticks that
+  fell while the widget was hidden; a one-shot timer that fell due while
+  hidden ticks once when the widget is shown again. Compute elapsed time
+  from `Date.now()`, never from a count of ticks:
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+// A timer does not tick while the widget is hidden: the time left comes
+// from the clock, not from the number of ticks.
+function tick(): void {
+  state.remainingMs = Math.max(0, endsAt - Date.now());
+  if (state.remainingMs > 0) {
+    return;
+  }
+  stop();
+  setRounds(state.rounds + 1);
+  log.info(`round ${state.rounds} finished`);
+  if (state.repeat) {
+    start();
+  }
+}
+```
+
+- **At most 16 timers** at once.
+
+For a clock, `timers.atEach` is the right tool: one repeating timer aligned
+on the boundaries of local time, which also wakes when the UTC offset
+changes (summer time) and once when the widget is shown again.
+
+<!-- source: widgets/clock/logic.ts -->
+```ts
+/** Ticks at each second or minute of local time, and shows the time now. */
+function start(): void {
+  clock?.cancel();
+  clock = timers.atEach(state.seconds ? "second" : "minute", tick);
+  tick();
+}
+```
+
+A duration that only has to advance on screen needs no timer at all: the
+`elapsed` element is advanced by OverCrow from a starting point the logic
+gives it. See the [`elapsed` element](elements.md#elapsed).
+
+## Time, dates and numbers
+
+Inside the VM, local time is UTC: `Date` never gives the user's time, and
+there is no `Intl`. The SDK formats instead, from `host.region`:
+
+| Helper | Gives |
+| --- | --- |
+| `formatTime(ms, { seconds })` | `14:08`, or `14:08:42`: 24-hour, in the user's time zone |
+| `formatDate(ms, { order })` | `17/07/2026`, `07/17/2026` or `2026-07-17`, in the user's date order by default |
+| `formatNumber(value, options)` | `1,234.5`, `1 234,5` or `1.234,5`: the user's separators, whatever the interface language |
+| `formatDuration(ms, options)` | `04:05`, `1:02:03`, or `04:05.67` with hundredths |
+| `localTime(ms)` | the fields of the instant in the user's time zone: `year`, `month`, `day`, `weekday`, `hour`… |
+
+<!-- source: widgets/clock/logic.ts -->
+```ts
+export function clockTime(now: number, seconds: boolean): string {
+  return formatTime(now, { seconds });
+}
+```
+
+<!-- source: templates/chart/logic.ts -->
+```ts
+export function latest(values: readonly number[]): string {
+  const last = values.at(-1);
+  return last === undefined ? "" : formatNumber(last, { maximumFractionDigits: 0 });
+}
+```
+
+A timestamp that comes from a service carries its own `offsetMinutes`: pass
+it to the helper (`formatTime(at, { offsetMinutes })`), so that a session
+recorded in another time zone shows the time it had there. Month and
+weekday names and 12-hour clocks are not provided.
+
+## Messages
+
+Put the texts of the widget in `locales/en.json` and `locales/fr.json`:
+two flat objects of strings with the same keys. Both files or neither.
+
+<!-- source: templates/list/locales/en.json -->
+```json
+{
+  "first": "Warm up",
+  "remaining": "{count} left",
+  "remove": "Remove",
+  "second": "Play three matches",
+  "third": "Update the drivers",
+  "title": "Today"
+}
+```
+
+`t(key, params)` returns the message of the user's language and replaces
+each `{name}` by `params.name`; a missing key gives the key itself. It
+works in the view and in the logic alike:
+
+<!-- source: templates/list/view.ocml -->
+```xml
+  <text class="summary">{t("remaining", { count: remaining(state.items) })}</text>
+```
+
+<!-- source: widgets/stopwatch/logic.ts -->
+```ts
+export function toggleLabel(running: boolean): string {
+  return t(running ? "pause" : "start");
+}
+```
+
+When the user changes OverCrow's language, the view is evaluated again
+with the new messages. A text that the logic computed and stored in the
+state is not: compute texts in functions the view calls, or refresh them in
+`onHost` when `"locale"` changes. The widget's name and its menu labels are
+in the manifest, not in the locales.
+
+`overcrow-widget check` warns when the view calls `t("key")` with a key
+that has no message, and refuses two files whose keys differ.
+
+## Drawing
+
+For what the elements cannot show, a `canvas` element is a surface that
+the logic paints with a list of commands: paths, fills, strokes, text and
+images. `draw(ref, commands)` replaces the whole content of the canvas
+named `ref`.
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+/** One dot per finished round, on the `dots` canvas. */
+function paint(): void {
+  const dots: DrawCommand[] = [];
+  for (let index = 0; index < Math.min(state.rounds, MAX_DOTS); index += 1) {
+    dots.push(["circle", 6 + index * 14, 6, 4], ["fill", "var(--color-accent)"]);
+  }
+  draw("dots", dots);
+}
+```
+
+Coordinates are logical pixels from the top-left corner of the canvas;
+colours are literal (`#rrggbb`) or colour tokens. OverCrow checks every
+command and draws them itself: there is no pixel access and no shader.
+Draw again when what you show changes, and when `host.theme` changes if you
+use literal colours.
+
+<!-- generated:draw-commands -->
+| Command | Arguments | Meaning |
+| --- | --- | --- |
+| `moveTo` | `x`: number -16384 to 16384; `y`: number -16384 to 16384 | Starts a subpath. |
+| `lineTo` | `x`: number -16384 to 16384; `y`: number -16384 to 16384 | Straight segment. |
+| `quadTo` | `cx`: number -16384 to 16384; `cy`: number -16384 to 16384; `x`: number -16384 to 16384; `y`: number -16384 to 16384 | Quadratic Bézier segment. |
+| `cubicTo` | `c1x`: number -16384 to 16384; `c1y`: number -16384 to 16384; `c2x`: number -16384 to 16384; `c2y`: number -16384 to 16384; `x`: number -16384 to 16384; `y`: number -16384 to 16384 | Cubic Bézier segment. |
+| `arc` | `cx`: number -16384 to 16384; `cy`: number -16384 to 16384; `r`: number -16384 to 16384; `start`: number -720 to 720; `end`: number -720 to 720 | Circular arc in degrees, clockwise. |
+| `rect` | `x`: number -16384 to 16384; `y`: number -16384 to 16384; `w`: number -16384 to 16384; `h`: number -16384 to 16384; `radius`: number -16384 to 16384 | Closed rounded-rectangle subpath. |
+| `circle` | `cx`: number -16384 to 16384; `cy`: number -16384 to 16384; `r`: number -16384 to 16384 | Closed circle subpath. |
+| `close` | none | Closes the subpath. |
+| `fill` | `color`: `<color>` | Fills and clears the current path. |
+| `stroke` | `color`: `<color>`; `width`: number 0 to 256 | Strokes and clears the current path. |
+| `text` | `x`: number -16384 to 16384; `y`: number -16384 to 16384; `text`: text ≤ 1 KiB; `size`: number 6 to 96; `color`: `<color>`; `align`: `start` \| `center` \| `end`; `family`: `ui` \| `mono` \| `display`; `weight`: `400` \| `500` \| `600` \| `700` | One line of text on its baseline. |
+| `image` | `src`: image source; `x`: number -16384 to 16384; `y`: number -16384 to 16384; `w`: number -16384 to 16384; `h`: number -16384 to 16384 | Draws an image scaled into the rectangle. |
+| `save` | none | Pushes transform, clip and alpha, ≤ 16. |
+| `restore` | none | Pops the state; a `restore` without a `save` is an error. |
+| `clip` | `x`: number -16384 to 16384; `y`: number -16384 to 16384; `w`: number -16384 to 16384; `h`: number -16384 to 16384 | Intersects the clip rectangle with this one. |
+| `translate` | `x`: number -16384 to 16384; `y`: number -16384 to 16384 | Translates. |
+| `rotate` | `degrees`: number -360 to 360 | Rotates. |
+| `scale` | `x`: number 0 to 8; `y`: number 0 to 8 | Scales. |
+| `alpha` | `value`: number 0 to 1 | Multiplies opacity. |
+<!-- /generated:draw-commands -->
+
+A chart, a gauge or a progress bar needs no canvas: the `chart`, `gauge`
+and `progress` elements draw them from values.
+
+## Logging
+
+`log.debug`, `log.info`, `log.warn` and `log.error` take one text. They
+appear in the terminal of `overcrow-widget dev` and nowhere else: an
+installed widget's logs are dropped. Never log user data.
+
+<!-- source: docs/content/examples/countdown/logic.ts -->
+```ts
+  log.info(`round ${state.rounds} finished`);
+```
+
+## What the logic cannot use
+
+`overcrow-widget check` lints the logic against what the VM runs and names
+the SDK replacement:
+
+| Code | Rule |
+| --- | --- |
+| `logic.syntax` | The module parses as ES2023; TypeScript types are allowed. |
+| `logic.import` | Its only import is `@overcrow/sdk`: no other module, file or package, no `export *`. |
+| `logic.dynamic_import`, `logic.import_meta` | No `import()` and no `import.meta`. |
+| `logic.eval`, `logic.function_constructor` | No `eval`, no `Function(…)` or `new Function(…)`. |
+| `logic.unavailable_global` | Every global it reads exists in the VM. `Intl`, `setTimeout`, `console`, `fetch`, `WebAssembly`, `SharedArrayBuffer`, `performance`, `WeakRef`, browser and Node.js globals do not. |
+| `logic.top_level_await`, `logic.top_level_this` | No top-level `await` or `for await`, no top-level `this`. |
+| `logic.syntax_version` | Nothing newer than ES2023: decorators, `using`, the regular expression `v` flag, import attributes. |
+| `logic.default_export` | The view calls named exports; `export default` is refused. |
+| `logic.missing_export` | Every function the view calls is exported. |
+| `logic.debugger` | `debugger` is a warning. |
+
+The lint helps you; it is not what protects the user. The sandbox, the
+VM's budgets and OverCrow's check of everything the widget sends do that.
+
+## What happens on a failure
+
+- An exception in a handler ends that turn; the widget keeps running, and
+  `overcrow-widget dev` shows the fault.
+- A turn longer than its budget (50 ms), a heap over its ceiling or too
+  many messages in a turn stop the widget. OverCrow shows a fixed error in
+  its frame and restarts it after 1, 5 and 15 seconds, at most three times.
+- A rejected promise of a service call is an ordinary error of your code:
+  catch it. See [errors](services.md#errors).
+
+The numbers are in [limits](limits.md#logic). The whole API of the SDK is
+in the [SDK reference](sdk.md).