react-x11 2.51.1 → 2.53.0

package/docs/testing.md

@@ -0,0 +1,494 @@
+# Testing
+
+`react-x11/test` renders your app through a **real X11 protocol connection
+to a real X server, in this process** — no `$DISPLAY`, no Xvfb, no native
+dependency, works on macOS. A test can read pixels back with `GetImage` and
+inject input through the server's own grab and focus machinery, so a
+passing test has exercised the path a user actually takes. The server is
+node-x11's `lib/xserver`, written in JavaScript; it arrives with ntk, so
+there is nothing new to install.
+
+**The harness drives the X11 backend**, on every platform including macOS —
+there is no `'cocoa'` backend for `renderX11()`, and `createRoot()`'s own
+choice does not apply because the harness always passes it an `app`. This
+is by design: macOS has no protocol to connect to in-process. An app
+targeting several backends tests its **tree, its queries and its
+behaviour** here — all shared — while anything genuinely per-backend (a
+native bezel's pixels, an `NSMenu`, a pasteboard flavour) is checked by
+running on that platform.
+
+```js
+import { test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  renderX11,
+  cleanup,
+  screen,
+  userEvent,
+  expectPixel,
+} from 'react-x11/test';
+
+afterEach(cleanup);
+
+test('adding a task', async () => {
+  const { ctx } = await renderX11(<Tasks />, {
+    fonts: { 'sans-serif': '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf' },
+  });
+
+  await userEvent.type(screen.getByRole('textbox'), 'buy milk\n');
+
+  screen.getByText('buy milk');
+  await expectPixel(ctx, 12, 40, '#2980b9', { tolerance: 8 });
+});
+```
+
+The vocabulary is Testing Library's. It is not Testing Library — there is
+no document for it to query — but `getByRole` / `userEvent.click` /
+`waitFor` mean here what they mean there.
+
+## `renderX11(element, options)`
+
+Mounts the tree and returns a handle **plus the queries bound to it**, so
+`const { getByText } = await renderX11(<App />)` reads the familiar way.
+
+| option            |                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `width`, `height` | the window (default 640×480)                                                     |
+| `screen`          | the display (defaults comfortably larger than the window — see below)            |
+| `backend`         | `'xserver'` (default) or `'mock'`                                                |
+| `fonts`           | `{ family: '/path/to.ttf' }` — **required for text pixels**                      |
+| `wrap`            | wrap in a `<window>`; default true unless the element is one                     |
+| `app`             | render into a connection you already have                                        |
+| `scale`           | pin the display scale — `2` renders as a retina panel would; default 1           |
+| `colorScheme`     | `'light'` (default), `'dark'`, or `'system'` to follow the real desktop          |
+| `appearance`      | pin the rest of the desktop's appearance — [see below](#the-desktops-appearance) |
+
+| on the result         |                                                                       |
+| --------------------- | --------------------------------------------------------------------- |
+| `ctx`                 | the window's 2d context — what the pixel helpers read                 |
+| `window`              | the live ntk `Window`                                                 |
+| `windowNode`          | the `WindowNode`: the paint, layout and event root                    |
+| `server`, `app`       | the X server and the connection, for anything this API does not cover |
+| `rerender`, `unmount` | re-render into the same root; take it down                            |
+
+**`fonts` is not optional for pixel assertions involving text.** Family
+resolution otherwise shells out to `fc-match`, which gives a different answer
+on every machine and no answer at all in a container — see the `sans-serif`
+note in [AGENTS.md](../AGENTS.md).
+
+**The screen is bigger than the window on purpose**, because on a real
+display it is. A press "outside the application" is what dismisses a menu,
+and it needs somewhere to land.
+
+## Queries
+
+`getBy*` (exactly one, or throw), `queryBy*` (one or null — the way to
+assert absence), `getAllBy*`, and `findBy*` — `getBy*` under
+[`waitFor`](#act-and-the-three-clocks), with its options, so it retries until
+the node appears and resolves once it is laid out. Four of each: `ByText`,
+`ByRole`, `ByTestName`, `ByPlaceholder`.
+
+```js
+getByText(/guestbook/); // substring, case-insensitive
+getByText('Save', { exact: true });
+getByRole('button', { name: 'Save' });
+getByTestName('name-field'); // matches a `data-testname` prop
+getByPlaceholder('Your name');
+```
+
+- `screen` is the same queries bound to the most recent render, **popups
+  included** — a `<popup>` is a child node of the window that opened it, so a
+  menu or a dialog is queryable without any special casing.
+- `within(node)` scopes them to a subtree.
+- `all(predicate?)` is the escape hatch: every node under the root, in paint
+  order, matched on anything — `screen.all((n) => n.kind === 'gauge')`.
+  `node.kind` is the element name, which is how an element with no text and
+  no role of its own is still reachable.
+- A miss prints the tree it searched, rather than leaving you with
+  `undefined is not an object`.
+
+**About roles.** `roleOf` answers from the same model the AT-SPI bridge
+publishes ([accessibility.md](accessibility.md)): an explicit `role` prop
+if there is one, else the element's own semantics — `textinput` and
+`textarea` report `textbox`, `window` and `popup` `window`, `image` `img`,
+`text` `text`; kinds with no accessibility meaning (`box`, `canvas`)
+answer their kind. The widgets name themselves — `Button` is `button`,
+`Checkbox` `checkbox`, `Switch` `switch`, `Radio` `radio`, `Select`
+`combobox` (its options `option`), `Slider` `slider`, `Tabs` `tablist`/
+`tab`/`tabpanel`, `Dialog` `dialog` — so what a
+test selects by is exactly what a screen reader hears.
+
+**And the bridge itself.** Importing `react-x11/test` sets `NO_AT_BRIDGE`,
+so a test run on a desktop never registers phantom applications with the
+live screen-reader registry. Tests that exercise the bridge deliberately
+point `AT_SPI_BUS_ADDRESS` at an in-process bus instead — see
+[accessibility.md](accessibility.md#testing-and-verifying).
+
+## Components
+
+The queries above see what a user sees. When a test needs the React side
+instead — _which component_ made this node, with what props and state — this
+is the layer for it. Prefer the user-visible queries when either would do.
+
+```js
+const row = screen.getByComponent('TaskRow'); // also RegExp or predicate
+within(row).getByText('buy milk'); // scoped to that instance
+
+ownerChainOf(node); // ['Label', 'TaskRow', 'App'] — who wrote the JSX
+sourceOf(node); // { file, line, column } of the JSX that made it
+```
+
+`getByComponent` returns, per rendered instance, the topmost host nodes of
+its output — the container `within()` wants next. Ownership is React's JSX
+owner (_who wrote the element_), so content passed as children belongs to
+the component whose JSX it appears in, and a miss lists the component names
+that are in the tree. All of this reads the debug info development React
+records on every fiber (the data [click-to-component](click-to-component.md)
+navigates by), so it needs no setup and no dependency, and returns nothing
+in production builds.
+
+### `inspect(node)` and `setHook`
+
+```js
+const c = await inspect(screen.getByText('buy milk'));
+c.name; // 'TaskRow' — the nearest mounted component
+c.props; // its live props object (treat as read-only)
+c.hooks; // [{ id, name: 'State', value, editable, source, subHooks }]
+
+await c.setHook(0, 41); // set a useState/useReducer value…
+await c.setHook(1, ['filter', 'text'], 'milk'); // …or a path inside one
+```
+
+This drives the **React DevTools backend in-process** — the same inspection
+and override path the DevTools app uses, minus its WebSocket: nothing
+listens on anything, and `ws` is never loaded ([devtools.md](devtools.md)).
+It needs the `react-devtools-core` package in your devDependencies; the
+queries above work without it.
+
+What to know before leaning on it:
+
+- **Reading hooks re-runs the component** once, output discarded and
+  `console` muted — that is how hook names are recovered. A render-counting
+  test will see it.
+- **Values:** `props` and editable hook values are the live objects;
+  everything else is DevTools' copy — primitives exact, deep objects as
+  the same previews the DevTools panel shows.
+- **Only `useState`/`useReducer` are settable** (`editable: true`; a
+  reducer is bypassed, not driven — no action runs). Hooks are addressed
+  by their `id`, an index the Rules of Hooks fix for the life of the
+  component. Anything else — an Effect, a Memo, a `useContext` value —
+  `setHook` refuses by name; for context, wrap a provider.
+- **Nearest component is tree ancestry** (what the DevTools panel would
+  select), where `getByComponent`/`ownerChainOf` are JSX ownership; the
+  two differ for content passed as children.
+- `setHook` resolves after React re-rendered and repainted (it is
+  `act`-wrapped), so a query straight after it sees the result.
+
+## Driving it
+
+`userEvent` is the layer to reach for: each call injects input **and**
+flushes what it caused, so it is async and there is nothing to remember.
+`fireEvent` is the synchronous half, for when a test needs one side of a
+gesture — wrap it in `act()` yourself.
+
+```js
+await userEvent.click(getByRole('button'));
+await userEvent.click(node, { modifiers: ['Shift'], button: 3 });
+await userEvent.hover(node);
+await userEvent.type(input, 'héllo\n'); // \n is Return
+await userEvent.tab({ shift: true });
+await userEvent.key(XK_ESCAPE); // react-x11/keysyms
+await userEvent.key(XK_DEAD_ACUTE); // then type 'e' for é — events.md#composition
+await userEvent.wheel(list, { deltaY: 3 }); // three notches, as buttons 4-7
+await userEvent.wheel(list, { deltaY: 0.25, smooth: true }); // a touchpad
+await userEvent.clickOutside(); // dismisses a menu — see below
+```
+
+Input goes through the server, so:
+
+**Grabs are real.** A `<popup grab>` is dismissed by a real press outside
+it. But note _where_ outside: react-x11's popups grab with **owner events**,
+so a press on one of the client's own windows is delivered normally — that is
+what keeps submenus and the owner window working. Only a press somewhere the
+client does not own reaches the grab holder. `userEvent.clickOutside()` is
+how a test says that; clicking another widget and expecting the menu to close
+is testing the wrong thing.
+
+**Focus is real**, so `trapFocus`, `autoFocus` and Tab traversal are
+exercised rather than simulated. There is no window manager, so `renderX11`
+gives the window input focus once at mount — otherwise keys would go to
+whatever the pointer happened to be over.
+
+**A smooth scroll is the one exception.** Whole notches go through the
+server as the button presses X really uses, but a touchpad's fraction of a
+notch is XI2, which the in-process server lacks, so `{ smooth: true }`
+delivers the `wheel` event straight to the window. Everything above it is
+still the real path: the dispatch, the chain, the default action.
+
+**Typing works for text the layout does not have.** `userEvent.type(input,
+'héllo')` binds a spare keycode for `é` on both the server's keymap and the
+client's cache, so a test can type real text without owning a keymap.
+
+**Drags are real too.** Because the pointer events are genuine, a
+drag-and-drop gesture is just three of them — with a real 4px threshold, so
+move before releasing:
+
+```js
+await act(async () => {
+  fireEvent.mouseDown(card);
+  fireEvent.mouseMove(card, { dx: 8 }); // past the threshold, still on the card
+  fireEvent.mouseMove(bin);
+  fireEvent.mouseUp(bin);
+});
+```
+
+`onDragStart`, `onDrop` and `onDragEnd` all run, and `e.items` carries the
+payload by reference. A drop from _another application_ needs a second X
+connection playing the foreign source — see
+[drag-and-drop.md](drag-and-drop.md).
+
+**A pointer event aims at a node's rect**, at its centre moved by
+`{ dx, dy }`, so a node with no rect throws and says why. Only a node no
+frame has laid out yet is told to `await act()`. The rest keep no rect
+however many frames run, and the error says what to do instead:
+
+- laid out at 0×0: give it a size, or point at an ancestor or a child that
+  has one. When the size is content still arriving, such as an image that
+  is loading, `waitFor` it;
+- `display: 'none'`, on the node or on an ancestor, hidden by React in an
+  `<Activity mode="hidden">` or a `<Suspense>` showing its fallback, or in a
+  `<window hidden>` or a `<popup hidden>`: show it first;
+- a nested `<text>` or an SVG shape, laid out as part of its paragraph or its
+  `<svg>`: point at that, with `{ dx, dy }`;
+- unmounted: query for whatever replaced it.
+
+A hidden or unmounted node throws even where it still has a rect. It keeps
+the one it was last laid out at, and what is there now is whatever was
+behind it: a button in a tab that was hidden sits exactly where the shown
+tab's button is, and a click aimed at it would land on that one.
+
+`mouseUp` and `mouseLeave`, and so `userEvent.unhover`, aim at nothing, so
+the node they are handed only names the connection and can be one the press
+or the hover took away. A release lets go wherever the pointer is, so move
+it first to release somewhere else. A leave moves the pointer to the
+screen's origin — which under `renderX11`, with no window manager to place
+the window, is the window's own top-left corner, so a node there is not
+left.
+
+## What a screen reader would hear
+
+`renderX11(element, { a11y: true })` adds `at` to the result: the
+assistive-technology spy, an in-process log of the same semantic feed the
+AT-SPI bridge serves to Orca — focus, state changes, text edits,
+announcements — observed at the hook seam, before any D-Bus. Synchronous,
+bus-free, and it runs wherever the suite runs.
+
+```js
+const { at } = await renderX11(<App />, { a11y: true });
+await userEvent.tab();
+assert.equal(at.focused().utterance, 'Save, button');
+await userEvent.key(XK_SPACE);
+assert.ok(at.since().some((e) => e.type === 'state' && e.state === 'checked'));
+```
+
+A composition is in there as itself: a dead key logs one `preedit` entry
+(`preedit: "´"`) and no insertion, and the letter that finishes it logs
+`preedit: cleared` and one `insert: "é"` — the same line the bridge draws
+with `:system`, which is how a test catches a screen reader that would echo
+a half-typed accent.
+
+A [registered element](extending.md#text-a-screen-reader-can-read) that
+reports its own text is observed through the same seam, so a package
+shipping an editor or a document view can assert what it says with no bus
+and no desktop — `test/a11y-custom-text.test.js` is the worked pair.
+
+`at.events()` / `at.since()` are precise facts, `at.transcript()` the
+one-line summaries, `at.focusables()` every keyboard stop in Tab order with
+its utterance — a nameless control reads `"(no accessible name)"`, which
+turns the most-missed accessibility bug into a one-line audit. The four
+canonical tests (focus order, keyboard trap, nothing nameless, states
+announced) live in `test/a11y-spy.test.js`, written to be copied; the model
+behind the wording is [accessibility.md](accessibility.md)'s own, not an
+imitation of Orca's.
+
+## `act`, and the three clocks
+
+`act(fn)` flushes everything between a state update and a pixel. There are
+three separate clocks in the way, and a wrapper that drives only the first
+stays flaky on pixel assertions:
+
+1. **React's** — `React.act` with `IS_REACT_ACT_ENVIRONMENT` set.
+2. **The wire** — events the injection produced are not in the tree yet.
+   The server writes them asynchronously, so a round trip on its own can
+   overtake them and `act` would return before the pointer move had been
+   dispatched at all, which looks exactly like a hover that does not work.
+3. **ntk's frame clock** — painting is scheduled through
+   `requestAnimationFrame`, paced behind the display's vertical blank (or a
+   server round trip where there is no Present extension). Pointer motion
+   waits for a frame too: ntk delivers a window's moves merged, once a frame,
+   so a move that lands just after a frame, such as the second of two hovers
+   in a row, waits out the rest of the frame interval. Synthetic input can
+   also leave a frame scheduled and never run. So `act` dispatches what each
+   window holds and runs the frame directly rather than waiting for either,
+   then round-trips so the server has actually processed the drawing.
+
+`waitFor(fn)` retries until `fn` stops throwing, `act`-ing between attempts —
+so waiting also _advances_. Reach for it when the thing you are asserting
+arrives on a clock none of those three is: a timer, an fs read, an image
+decode, another process. A `Button`'s hover needs no waiting, though it is an
+event, a re-render of React state and a frame: `act` runs all three, so the
+repaint is on screen when `userEvent.hover` resolves.
+
+It `act`s once more after the attempt that passes, so what it resolves with
+is on screen and laid out: a row that arrived from an fs read or a timer
+committed outside `act`, and without that last frame the click after it
+would throw `has no laid-out rect yet`.
+
+```js
+const row = await waitFor(() => screen.getByText('notes.txt'));
+await userEvent.click(row); // laid out: waitFor ran the frame
+```
+
+## When the connection ends
+
+`act()`, `waitFor` and `cleanup()` each drain the connection with a round
+trip, and a connection that has gone has nothing left to drain, so there they
+resolve without one. A test can close its app, dispose of it or have the
+server drop it, and still get through its own teardown.
+
+What an app does when its display goes away — `createRoot`'s
+[`onDisconnect`](README.md) — is tested by ending the connection from the
+server's side, the way `xkill` does. An option `renderX11` does not know is
+handed to `createRoot`:
+
+```js
+const seen = [];
+const { app, window } = await renderX11(<App />, {
+  onDisconnect: (reason) => seen.push(reason),
+});
+app.X.KillClient(window.id);
+await act();
+assert.deepEqual(seen, ['closed']);
+```
+
+`app.close()` is not the same test. Over the in-process server, a client that
+closed its own connection never hears it end, so `onDisconnect` never fires.
+
+## Pixels
+
+```js
+await expectPixel(ctx, 10, 10, '#2980b9', { tolerance: 8 });
+await waitForPixel(ctx, 10, 10, '#c0392b', { timeout: 2000 });
+const [r, g, b] = await pixelAt(ctx, 10, 10);
+const n = await countPixels(ctx, { width: 80, height: 40 }, '#c0392b');
+await toPNG(ctx, '/tmp/shot.png', { width: 320, height: 240 });
+```
+
+A pixel proves the tree, the layout, the clip, the paint order, the colour
+parsing and the wire encoding at once — the only assertion that catches
+everything committing correctly and nothing reaching the screen. The
+readback is straight **RGBA**, as on a canvas, and antialiasing means every
+comparison takes a **tolerance**.
+
+## Animations
+
+```js
+const clock = withFrameClock(); // install it BEFORE the render
+await rerender(<Fading on />);
+clock.advance(100);
+await act(); // part way
+clock.advance(200);
+await act(); // arrived
+clock.restore();
+```
+
+Install it **before** the render. Every timestamp in the tree has to come
+from the same clock: mixing a real start time with a frozen `now` gives a
+transition that never progresses.
+
+## The desktop's appearance
+
+The built-in palette follows the desktop, so `renderX11` **pins** it —
+otherwise a pixel assertion would pass on a light desktop and fail on a
+dark one. The pin is light unless the render says otherwise, and it covers
+everything `useSystemAppearance()` reports, so a component that follows
+reduced motion, contrast or the accent is tested the way one that follows
+the scheme is:
+
+```jsx
+await renderX11(<App />); // light
+await renderX11(<App />, { colorScheme: 'dark' });
+await renderX11(<Spinner />, { appearance: { reducedMotion: true } });
+await renderX11(<App />, { colorScheme: 'system' }); // the real desktop
+```
+
+`appearance` pins from the **first** render, which matters wherever the first
+render decides something: a loop that never starts is a different path from
+one that starts and is stopped. To change a value under a mounted tree — the
+case a component that follows the desktop has to get right — use
+`setAppearance`:
+
+```jsx
+import { renderX11, setAppearance, screen } from 'react-x11/test';
+
+await renderX11(<Spinner />, {
+  colorScheme: 'dark',
+  appearance: { reducedMotion: true },
+});
+screen.getByText('paused');
+await setAppearance({ reducedMotion: false });
+screen.getByText('spinning'); // re-rendered and repainted, and still dark
+```
+
+It merges over the pin, so naming one value keeps the rest, and it flushes the
+way `userEvent` does: the re-render, the palette's repaint and the frame are
+done when it resolves. The appearance is the desktop's, so there is one per
+process — every mounted root sees the change, as every window would.
+
+`reducedMotion` is the appearance's answer, and it is not the one core's own
+motion follows: `ProgressBar` and the style loops read
+`useDesktopSettings().animations`, a separate setting from a separate source
+([system.md](system.md)) that the two can disagree on. The in-process server
+has no settings daemon, so it stays at its default — on — whatever is pinned
+here.
+
+Three mistakes throw rather than pass quietly:
+
+- **A key outside `useSystemAppearance()`'s fields.** `reduceMotion: true`
+  would otherwise pin nothing and render the component the way it always
+  does. `source` is not settable either: under a pin it reads `'test'`.
+- **`colorScheme: 'system'` with `appearance`.** The first follows the real
+  desktop and the second pins it; name `colorScheme` inside `appearance`
+  instead.
+- **`setAppearance` before `renderX11`.** The render pins as it mounts and
+  would replace what was set, so it throws and says to pass `appearance`.
+
+`cleanup()` releases the pin, and only the pin. A pinned value is never
+written to the cache a real app starts its first frame from
+([appearance.md](appearance.md)), so a suite run on a developer's desktop
+leaves that desktop's remembered answer as it found it, and an answer the
+desktop sends while a pin is held is dropped rather than painted into the
+next test.
+
+## The mock backend
+
+`backend: 'mock'` swaps the server for a fake 2d context that records draw
+operations. No server, no connection, much faster, and no pixels — good for
+asserting on layout and on the node tree, which is most tests. Input
+injection is not available and says so.
+
+With no connection there is also nothing to embed into, so the mock answers
+the way the Cocoa backend does: `useSupports('embedding')` is false, and a
+`<foreign>` in the tree lays out as an empty box and reports one `onError`
+rather than failing the mount. A component that asks before rendering one
+mounts its fallback here; one that does not still mounts.
+
+A batch records as the fills it stands for: `ctx.fillRects([[x, y, w, h], …])`
+leaves one `fillRect` operation per rectangle, so an assertion on what a
+drawing painted holds whether or not it batched.
+
+## Testing Library itself
+
+It does not work here and no shim will fix it: its queries are built on a
+document ([ecosystem.md](ecosystem.md#render-time) lists the failure
+modes). This page is the replacement.

package/docs/typescript.md

@@ -0,0 +1,75 @@
+# TypeScript
+
+Types ship with the package. There is no `@types/react-x11`, and nothing to
+build — the declarations are hand-written `.d.ts` files next to the
+JavaScript they describe.
+
+## Setup
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react-x11",
+    "moduleResolution": "bundler", // or "node16" / "nodenext"
+  },
+}
+```
+
+`jsxImportSource` is the whole configuration. Without it JSX resolves
+against React's namespace, which describes the DOM.
+
+## Why a JSX runtime and not an augmentation
+
+react-x11 cannot merge its elements into React's `JSX` namespace: `text`,
+`image`, `canvas`, `html` and `svg` are already declared there by
+`@types/react` with DOM props, and declaration merging cannot replace them.
+So `react-x11/jsx-runtime` re-exports React's runtime with a `JSX` namespace
+of its own that holds the react-x11 elements _and nothing else_:
+
+```tsx
+<div /> // error: Property 'div' does not exist on type 'JSX.IntrinsicElements'
+```
+
+If you need extra elements of your own, `IntrinsicElements` is an interface,
+so merging still works:
+
+```ts
+declare module 'react-x11/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'my-element': { value?: number };
+    }
+  }
+}
+```
+
+## What is typed
+
+|                             |                                                                               |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `src/types/style.d.ts`      | `Style`, `StyleProp`, the yoga enums, state blocks, transitions, size queries |
+| `src/types/events.d.ts`     | `SyntheticEvent` and the mouse / wheel / keyboard / focus shapes              |
+| `src/types/nodes.d.ts`      | what a `ref` gives you: `DrawnNode`, `ScrollableNode`, ntk's `Window`         |
+| `src/types/elements.d.ts`   | every host element's props, including the 3D scene                            |
+| `src/types/components.d.ts` | the widget set, `Theme`, the anchoring helpers                                |
+| `src/index.d.ts`            | the entry: `createRoot`, `render`, and re-exports of the above                |
+
+A few deliberate looseness decisions:
+
+- **`Color` is `string`.** It is a CSS colour or a `$token` resolved against
+  the nearest `theme`; narrowing it would reject valid values without
+  catching much.
+- **`ctx` and `gl` are `any`.** They are ntk's 2d context and its indirect
+  GLX context, and ntk ships no types. Typing them here would mean
+  maintaining a second, drifting copy of ntk's API.
+- **`Renderer` is `any`.** It is the react-reconciler instance, an escape
+  hatch rather than a supported surface.
+
+Style values are as precise as the runtime is: `flexDirection` only takes
+the four yoga values, a state block only takes paint properties (the same
+rule `createStyles` enforces at runtime), and `width` takes
+`number | '50%' | 'auto'`.
+
+Design notes: [design/typescript.md](../design/typescript.md).