# helder.build

> Helder is a high-performance UI and graphics stack for native apps on desktop and mobile, and for the web. Its studio, at https://helder.build/studio/, runs entirely in the user's browser (recent Chrome or Edge, WebGPU): it draws design files at once, builds Haxe apps with a compiler in the page, and keeps projects in the browser's storage. No account. An agent makes the files; the user opens a link and sees them live.

This file tells an agent how to build an app in helder.build that works. It is generated from helder's source (commit 01e33462cd): https://github.com/benmerckx/helder

## How an agent works with it

Two ways in, the same result: a link the user opens in their browser.

### 1. Over MCP (best: you see what the user sees)

Add the relay, an MCP server over Streamable HTTP, no account:

    claude mcp add --transport http helder https://helder.build/mcp

Any other MCP client: a remote (HTTP) server at `https://helder.build/mcp`, e.g.

    {"mcpServers": {"helder": {"type": "http", "url": "https://helder.build/mcp"}}}

Tools:

- `project.create {name?, files?}`: a draft from your files (`{path: text}`); answers `{id, url}`. Give the user the `url` (`https://helder.build/studio/#draft=<id>`) and ask them to open it.
- `project.read {id, path?}`: a file as it is now (the user's own edits in the studio come back to the draft), or the list of files and whether a studio tab has the draft open.
- `project.patch {id, path, edits: [{old, new}]}` or `{id, path, text}`: each `old` must occur exactly once in the file; `text` replaces the file or makes a new one. The open tab applies it live, through its history (the user can undo it), and answers what happened.
- `project.status {id}`: whether a tab has it open, and what the tab reported after the last change: `diagnostics`, each screen's node tree (tags, boxes, texts, colours, `file:line`) and a small PNG of each screen. `stale: true` means the tab has not reported on the latest version yet: wait a moment and ask again.

The relay only stores and relays text: the user's browser runs, checks and draws everything, so `project.status` is empty until the user has opened the link. The loop: create, give the link, patch, check `project.status` (its diagnostics and PNGs), and only then tell the user it is done.

Limits: a draft is at most 1 MB of text and 200 files (paths relative, no dot directories); it expires 30 days after its last change; calls are rate-limited per IP (240 calls and 10 drafts a minute).

### 2. Without MCP: a link you make yourself

    https://helder.build/studio/#import=<data>

`<data>` is the JSON `{"name": "my-app", "files": {"app.helder": "<Design>...</Design>"}}`, in one of three forms:

- percent-encoded JSON as it is (`encodeURIComponent(json)`): the easiest to write without running code;
- base64url of the JSON's UTF-8 bytes (starts with `ey`);
- `z.` and base64url of the JSON deflated (deflate-raw, no zlib header): the shortest. Python: `base64.urlsafe_b64encode(zlib.compress(data, 9)[2:-4]).rstrip(b'=')`; Node: `zlib.deflateRawSync(data).toString('base64url')`.

The studio opens it as a new project in the browser's storage. Nothing is sent to a server (the part after `#` stays in the browser). Limits: 1 MB and 200 files after decoding; the whole URL at most 2 MB (Chrome's limit); links pasted into chats and mail are safest under about 8 KB, so prefer the `z.` form, and MCP for anything larger. The link is not kept in sync: for changes, make a new link (it opens as a new project).

## What to write: start with a design file

A new helder.build project is one design file, `app.helder`. Design files are drawn by the studio at once, nothing built, so they are the safest thing to make and the fastest to see. Write the screens as design files first; add Haxe code only when something must run (state, input, logic).

A design file (`*.helder`) is helder's markup alone:

- the root is `<Design>`; its children are `<Frame>`s;
- a `<Frame name="Home" width={390} height={844} canvas:at="0 0">` is a screen on the canvas: `name` (unique in the file), its size in points (a phone is 390 by 844), `canvas:at="x y"` its place (put frames side by side: `0 0`, `430 0`, `860 0`...); its other attributes style it like a `view`;
- `<note>...</note>` and `canvas:*` attributes are for the editor and are not drawn;
- inside a frame: the elements and attributes below, with literal values only: strings (`color="#111827"`, `padding="16 24"`) and numbers (`font-size={32}`). No code in a design file: an expression (`{items.length}`), a component, an unknown element or a value its attribute rejects is outlined in red and reported in `project.status`'s diagnostics;
- a frame's screen is named `<file>#<frame>` (`app.helder#Home`);
- layout is flexbox (a `view` stacks its children in a column; `direction="row"` for a row; `row-gap`, `column-gap`, `padding`, `align-items`, `justify`, `grow`), sizes in points;
- text goes in `<text>`; a `view` holds no bare text;
- images by path (`<image src="logo.png"/>`) are not drawn in the browser yet: use shapes (views with `background` and `radius`) and `<icon name="check"/>` (lucide's icons by name).

The studio's new project, `app.helder`, a good start:

```
<Design>
	<Frame name="Home" width={390} height={844} canvas:at="0 0" background="#ffffff" padding="64 24 24" row-gap={12}>
		<note>A design file: drawn at once, nothing built. Select, move, resize; the inspector edits it.</note>
		<text tag="title" font-size={32} font-weight={700} color="#111827">Hello</text>
		<text color="#6b7280">A first screen. Edit the text, the colours, the spacing.</text>
		<view direction="row" column-gap={8} padding="16 0 0">
			<view padding="10 16" background="#111827" radius={10}>
				<text color="#ffffff" font-weight={600}>Start</text>
			</view>
			<view padding="10 16" radius={10} border-width={1} border-color="#d1d5db">
				<text color="#111827">Later</text>
			</view>
		</view>
	</Frame>
	<Frame name="Next" width={390} height={844} canvas:at="430 0" background="#f9fafb" padding="64 24 24" row-gap={16}>
		<text font-size={24} font-weight={700} color="#111827">Next</text>
		<view padding="16" background="#ffffff" radius={12} border-width={1} border-color="#e5e7eb" row-gap={4}>
			<text font-weight={600}>A card</text>
			<text color="#6b7280">Frames are screens. Add one beside this.</text>
		</view>
	</Frame>
</Design>
```

helder's design example (examples/design/app.helder):

```
<Design>
	<Frame name="Home" width={390} height={844} canvas:at="0 0" background="#f8fafc" padding="56 24 24" row-gap={16}>
		<note>The list as it opens: three items, one done.</note>
		<text tag="title" font-size={28} font-weight={700} color="#3b82f6">todos</text>
		<view direction="row" column-gap={8} align-items="center" padding="10 12" background="#ffffff" radius={10} border-width={1} border-color="#e2e8f0">
			<text grow={1} color="#94a3b8">What needs to be done?</text>
			<view padding="6 12" background="#3b82f6" radius={8}>
				<text color="#ffffff" font-weight={600}>Add</text>
			</view>
		</view>
		<view row-gap={1} background="#e2e8f0" radius={10} overflow="hidden">
			<view direction="row" column-gap={12} align-items="center" padding="12 14" background="#ffffff">
				<view width={18} height={18} radius={9} background="#22c55e"/>
				<text grow={1} color="#94a3b8">Sketch the home screen</text>
			</view>
			<view direction="row" column-gap={12} align-items="center" padding="12 14" background="#ffffff">
				<view width={18} height={18} radius={9} border-width={2} border-color="#cbd5e1"/>
				<text grow={1}>Pick the colours</text>
			</view>
			<view direction="row" column-gap={12} align-items="center" padding="12 14" background="#ffffff">
				<view width={18} height={18} radius={9} border-width={2} border-color="#cbd5e1"/>
				<text grow={1}>Write the list in code</text>
			</view>
		</view>
		<text font-size={13} color="#64748b">2 items left</text>
	</Frame>
	<Frame name="Empty" width={390} height={844} canvas:at="430 0" background="#f8fafc" padding="56 24 24" row-gap={16} align-items="center">
		<text font-size={28} font-weight={700} color="#3b82f6" align-self="start">todos</text>
		<view grow={1} justify="center" align-items="center" row-gap={8}>
			<image src="empty.svg" width={64} height={64}/>
			<text font-size={17} font-weight={600}>Nothing to do</text>
			<text color="#64748b">Add an item to get started.</text>
		</view>
	</Frame>
</Design>
```

## Elements and attributes (helder.ui)

From helder.ui's README (src/helder/ui/README.md, "Markup"):

Intrinsic elements: `view` (a box), `text` (a run of text), `scroll` (a box
that scrolls), `image` (an `ImageNode`: `src={image}` or `src={svg}`, `fit="cover"`, `object-position="left top"`).
Inside a `text`, elements are spans of rich text: `span`, `b`, `i` or
`text` again, each with its own style (colour, weight, size...) and
handlers (a link: `<span color="#2563eb" onClick={...}>`); lines are as
high as CSS makes them, their spans on one baseline.
Attributes:

- any Style property, in camelCase or kebab-case, with values as CSS
  writes them: `direction="row"`, `justify="space-between"`,
  `padding="8 12"`, `width="50%"`, `background="#3b82f6"`, `radius={6}`;
  `style={...}` takes a typed `StyleProps` object;
- events: `onClick`, `onPointerDown`, `onPointerUp`, `onPointerMove`,
  `onPointerEnter`, `onPointerLeave`, `onPointerCancel`,
  `onLostPointerCapture`, `onWheel`, `onKeyDown`, `onKeyUp`,
  `onTextInput`, `onFocus`, `onBlur`, `onFocusIn`, `onFocusOut` (bubbling) (an `Event -> Void`);
  `onPress` (`Node.onActivate`: a click, or Enter or Space unless `onKeyDown`
  took it, as a DOM button's click); the gestures `onTap`, `onPan`
  (`pan-axis="x"`, `pan-min-pointers`), `onPinch`, `onScale` (a
  recogniser made on the node, given to its handler: a `Tap`, a `Pan`, a
  `Scale`). `helder.ui.view.NodeEvents` declares them (NodeRenderer's
  `@:events`, the neutral elements' in every renderer), and markup checks
  each handler against it: a function of its event or of none
  (`onPress={() -> ...}`), an untyped parameter typed as it
  (`onPan={g -> x(g.tx)}`, `onInput={e -> name(e.text)}`); another type, a
  Dynamic value or a name not there is a compile error at the attribute
  (helder.view's README);
- `key-context="Viewer zoomed"` (what the node is to the keymap),
  `actions={[Actions.handle(ViewerAction, a -> ...)]}` (its action
  handlers), `track-focus={handle}` (a `FocusHandle` tied to it),
  `tab-index={1}` (Tab's order): see Actions and keymaps below;
- `focusable`, `ref={n -> ...}` (the node), `tag="name"` (for `Node.find`);
  `id` none here (a page's element's, where a page's renderer realises
  the element).

The elements are also the neutral ones of single-source components
(`@:neutral`, src/helder/view/README.md): `view:button`, `view:label`... and
`text:p`, `text:h2`... are a view and a text here, the element of that name
in a page; `<icon name="check"/>` draws lucide's icon of that name
(`helder.ui.widgets.Icons`, an inline SVG in a page; `mirrored` flips it
right to left, `data-mirrored` in a page); `<field/>` and
`<field:textarea/>` are a text field (`TextField`, `TextArea`: native
where `Ui.policy` says; a page's `<input>`, `<textarea>`): `value`,
`placeholder`, `type` (`password`: dots), `rows`, `readonly`,
`maxlength`, `spellcheck` (the platform's checker on its words: a text
area's by default, a field's asked; misspelled words underlined with a red
wave, their corrections and Add to Dictionary in a right click's menu;
`helder.text.Spell`, off in the deterministic modes), `inputmode` and `autocomplete` (a page's), `onInput` (its
text changed by its user: `e.text`), its own editing after the markup's
`onKeyDown`... unless that prevented the default; a ref of theirs gets an `helder.ui.Part` (Node is one: `focus`,
`rect`, `scrollIntoView`, `contains`, `attr`, `rtl`, `capture`: a press's
moves and release to it (in a handler, that event's pointer: a finger's too); `select`: a field's selection).
- drag and drop: `drag-data={value}` makes a node draggable; `onDragStart`,
  `onDragEnd` (`e.dropped`) on the source, `onDragOver` (`e.preventDefault()`
  accepts), `onDragLeave` and `onDrop` (`e.data`) on targets; Escape cancels.

A phone's safe area (the insets its bars, notch, island, cutout or home
indicator leave clear) is CSS's `env()`: a literal attribute naming
`env(safe-area-inset-top)` (`-right`, `-bottom`, `-left`; a fallback after
a comma for a name it does not know) is bound to the main window's insets
in UI pixels (`SafeArea.insets`, a signal; UiWindow sets it from
`helder.os.Window.safeTop`... over the scale) and set again when they
change (a rotation, the bars hidden): `padding-top="env(safe-area-inset-top)"`,
`padding="calc(env(safe-area-inset-top) + 8px) 16px"`,
`margin-bottom="max(12px, env(safe-area-inset-bottom))"` (`calc()`,
`max()` and `min()` of pixels fold to one length). Each Ui has its own as
`ui.safeArea` (0 on the desktop and the web); a `<Scene>`'s box gives the
part over it (`SceneBox.safeArea()`), for a game's HUD over a scene on the
whole screen.

A desktop window's title bar can be inset into the app
(`<Surface titlebar="inset">`, helder.os's `TitleBar`): the content runs
under it and the app lays out the window's buttons with
`<WindowControls/>` (`helder.ui.widgets.WindowButtons`: on macOS a box of
the system's own buttons' size, the buttons placed at it after each
layout; on Windows minimise, maximise and close drawn, 46 by 32, the close
button red when hovered; on Linux round ones; nothing in the browser, on a
phone or with the system's title bar). A node with `drag-region` moves the
window when pressed (what takes presses inside it, a button or a field,
stays the content's: `Ui.titleHit`, which each system's code asks at a
press, Windows at each WM_NCHITTEST); `env(titlebar-area-x)`, `-y`,
`-width` and `-height` are the bar's area free of the buttons (the Window
Controls Overlay's names, bound as the safe area's; without an inset
title bar the fallback). Tests: `TitlebarArea.test.hx`.

```haxe
<Surface title="Studio" titlebar="inset">
	<view direction="row" drag-region height="env(titlebar-area-height, 40px)" padding-left="env(titlebar-area-x)">
		<text>Studio</text><view grow={1}/><WindowControls/>
	</view>
</Surface>
```

A value that is a signal, a memo or a function is reactive: the attribute,
text or region follows it. In a `view`, text and text-valued holes next to
each other become one `TextNode`.

Tags and attribute names are resolved at compile time, so a program links
only the nodes, attributes and value parsers its markup names (a gradient
parser only with a gradient, image nodes only with `image`). A name none of
them has, a spread (`{...props}`) or `NodeRenderer.setAttribute` looks the
name up at run time and links them all.

The intrinsic elements as helder.ui's renderer defines them (src/helder/ui/view/NodeRenderer.hx):

```
helder.view's renderer for helder.ui's nodes (helder.ui.Node names it:
@:rendered; a <Surface>'s children, UiView): the tree that the
drawn backend (helder.ui.draw) displays.

Intrinsic elements: view (a Node), text (a TextNode of its children's
text; elements in it are its spans: span, b, i, or text again), scroll (a
Node with Overflow Scroll), image (an ImageNode: src, an Image, an
AnimatedImage, played, or an Svg, drawn in the node's color; object-position
("left top", CSS's), its place; fit, "fill",
"contain", "cover" or "none"; mirrored, flipped right to left), icon (an
image, its Svg), field and field:textarea (a text field, one line or
several: helder.ui.widgets' TextField and TextArea; value, placeholder,
type, rows, readonly, maxlength, spellcheck; onInput, its text changed by its
user); view:button,
view:label... and text:p, text:h2... (a view, a text: the element of that
name where a page's renderer realises them, helder.web's); elements registers more. Their
attributes: Style properties (StyleAttrs: direction="row", padding={8},
background="#3b82f6"; style={StyleProps} for several), the events
(onClick, onPress (a click, or Enter or Space: Node.onActivate), onPointerDown, onPointerUp, onPointerMove, onPointerEnter,
onPointerLeave, onPointerCancel, onLostPointerCapture, onWheel, onKeyDown, onKeyUp, onTextInput, onComposition,
onFocus, onBlur, onFocusIn, onFocusOut, the drag events, onResize (its
laid-out size changed: Event.target's width and height): Event -> Void;
the gestures, onTap, onPan (pan-axis "x" or "y", pan-min-pointers),
onPinch, onScale: a recogniser on the node (helder.ui.gesture), its
handler given it, a Tap, a Pan, a Scale; declared by NodeEvents, which
markup checks handlers against: @:events);
a node's own handler, a field's editing, after the markup's unless it
prevented the default), focusable, selectable,
drag-data, tag, and what the node is to assistive technology (Semantics:
role, label, description, href, checked, selected, expanded, level, disabled,
value-now, value-min, value-max, value-text, pos-in-set, set-size, hidden), and what a theme
styles it as (Rule: slot, variant, size, data-* and aria-* attributes,
data-state="checked"). A text node holds
text: its text children are its text, its elements its spans.

Pay for what is used: markup's literal tags and attribute names are
resolved at compile time (createElement inline, setProperty and setter
macros, AttrMacro), so that a program links the nodes, attributes and
value parsers its markup names; a name known only at run time
(setAttribute: a spread, Dynamic) reaches them all.
```

### Style attributes

Every Style property is an attribute, in kebab-case (or camelCase), its value as CSS writes it. Generated from src/helder/ui/Style.hx: the property, its type there, its note.

| attribute | type | note |
|---|---|---|
| `display` | `flex`, `none`, `grid`, `block` | not laid out nor drawn when None |
| `position` | `relative`, `absolute`, `sticky` |  |
| `direction` | `column`, `row`, `column-reverse`, `row-reverse` | the main axis (Column, as React Native and Yoga: a UI stacks) |
| `wrap` | Bool | items flow into more lines when the main size is too small |
| `justify` | `start`, `end`, `center`, `space-between`, `space-around`, `space-evenly`, `normal` |  |
| `align-items` | `auto`, `start`, `end`, `center`, `stretch`, `baseline` | the children's default alignment across the main axis |
| `align-self` | `auto`, `start`, `end`, `center`, `stretch`, `baseline` | this node's alignment in its parent (Auto: the parent's alignItems) |
| `align-content` | `start`, `end`, `center`, `stretch`, `space-between`, `space-around`, `space-evenly`, `normal` |  |
| `grid-template-columns` | Array<Grid.Track> | the explicit grid's columns and rows (Grid.tracks: "1fr 200px auto"; none: one empty array shared) |
| `grid-template-rows` | Array<Grid.Track> | the explicit grid's columns and rows (Grid.tracks: "1fr 200px auto"; none: one empty array shared) |
| `grid-template-areas` | Null<Grid.GridAreas> | the explicit grid's named areas (Grid.GridAreas.parse: "'head head' 'side main'"), which make it at least as many columns and rows (beyond the templates' sized as auto tracks) |
| `grid-auto-columns` | Grid.Track | the size of the tracks auto-placement adds beyond them |
| `grid-auto-rows` | Grid.Track | the size of the tracks auto-placement adds beyond them |
| `grid-auto-flow` | Grid.GridFlow | what auto-placement fills first: rows (each across, then the next) or columns |
| `grid-column` | Grid.GridPlacement | the lines this node spans in a grid (Grid.GridPlacement.parse: "1 / 3", "span 2") |
| `grid-row` | Grid.GridPlacement | the lines this node spans in a grid (Grid.GridPlacement.parse: "1 / 3", "span 2") |
| `grid-area` | String | both (Grid.area: "header", "1 / 2 / 3 / 4") |
| `justify-items` | `auto`, `start`, `end`, `center`, `stretch`, `baseline` | in a grid: the children's default alignment in their areas along a row, and this node's (Auto: its parent's justifyItems) |
| `justify-self` | `auto`, `start`, `end`, `center`, `stretch`, `baseline` | in a grid: the children's default alignment in their areas along a row, and this node's (Auto: its parent's justifyItems) |
| `grow` | Float | flex-grow |
| `shrink` | Float | flex-shrink |
| `basis` | Dim | flex-basis (Auto: the main size, else the content's) |
| `flex` | Float | grow, shrink and basis at once (CSS's flex shorthand): a number n is n 1 0%, as CSS's; markup also "none" (0 0 auto), "auto" (1 1 auto), "2 0 40px" |
| `width` | Dim | the border box's size |
| `height` | Dim |  |
| `min-width` | Dim | (Auto: 0) |
| `min-height` | Dim |  |
| `max-width` | Dim | (Auto: none) |
| `max-height` | Dim |  |
| `aspect-ratio` | Float | width / height when one of them is auto (0: none) |
| `padding` | EdgesValue |  |
| `margin` | EdgesValue |  |
| `padding-top` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `padding-right` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `padding-bottom` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `padding-left` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `margin-top` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `margin-right` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `margin-bottom` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `margin-left` | Float | one side of each (CSS's padding-top...: Tailwind's pt-2 and px-4 from separate rules; a margin's side may be Edges.AUTO, ml-auto) |
| `border-width` | Float | on all four sides, inside the border box |
| `borders` | Null<EdgesValue> | each side's (CSS's border-top-width...; null: borderWidth on all four) |
| `row-gap` | Float | between lines (Column: between items) |
| `column-gap` | Float | between items (Column: between lines) |
| `gap` | Float | both gaps at once (CSS's gap shorthand; markup "8 12": the rows', then the columns') |
| `left` | Dim | Absolute: the offsets from the parent's padding box; Relative: shifts |
| `top` | Dim |  |
| `right` | Dim |  |
| `bottom` | Dim |  |
| `inset` | Dim | the four offsets at once (CSS's inset shorthand; markup "10 20": as margins write them) |
| `overflow` | `visible`, `hidden`, `scroll` | what overflows it, on both axes (CSS's shorthand); read, the two together: Scroll if either scrolls, else Hidden if either clips. As CSS's, both axes clip when either does; an axis scrolls by the wheel, the keys and a scrollbar only where it is Scroll (Hidden: by scrollTo) |
| `overflow-x` | `visible`, `hidden`, `scroll` | what overflows it, on both axes (CSS's shorthand); read, the two together: Scroll if either scrolls, else Hidden if either clips. As CSS's, both axes clip when either does; an axis scrolls by the wheel, the keys and a scrollbar only where it is Scroll (Hidden: by scrollTo) |
| `overflow-y` | `visible`, `hidden`, `scroll` | what overflows it, on both axes (CSS's shorthand); read, the two together: Scroll if either scrolls, else Hidden if either clips. As CSS's, both axes clip when either does; an axis scrolls by the wheel, the keys and a scrollbar only where it is Scroll (Hidden: by scrollTo) |
| `background` | Color |  |
| `border-color` | Color |  |
| `radius` | Float | the corners' radius |
| `corners` | Null<CornersValue> | each corner's (CSS's border-radius with several values; null: radius on all four) |
| `opacity` | Float | of the node and its subtree |
| `cursor` | Cursor |  |
| `background-image` | Null<Gradient> | over the background colour, under the border: a CSS gradient (Gradient.parse; null: none) |
| `shadow` | Null<Shadow> | under the background (null: none) |
| `outline-width` | Float | a line around the border box, over the node's content: outlineWidth wide (0: none), outlineOffset outside it (negative: inside), in outlineColor (null: the text colour), its corners the box's grown by both, as Chromium draws CSS's solid outline; markup's outline="2px solid red" sets them, outline="none" none |
| `outline-offset` | Float | a line around the border box, over the node's content: outlineWidth wide (0: none), outlineOffset outside it (negative: inside), in outlineColor (null: the text colour), its corners the box's grown by both, as Chromium draws CSS's solid outline; markup's outline="2px solid red" sets them, outline="none" none |
| `outline-color` | Null<Color> | a line around the border box, over the node's content: outlineWidth wide (0: none), outlineOffset outside it (negative: inside), in outlineColor (null: the text colour), its corners the box's grown by both, as Chromium draws CSS's solid outline; markup's outline="2px solid red" sets them, outline="none" none |
| `outline` | Float | a solid outline this wide in the text colour (CSS's shorthand; markup also "2px solid red", "none") |
| `user-select` | `auto`, `none`, `text`, `all` | whether its text can be selected by the pointer (UserSelect; null: the parent's) |
| `field-sizing` | `fixed`, `content` | how a text field is sized where this style gives no size (FieldSizing; null: Fixed) |
| `scrollbar-width` | `auto`, `thin`, `none` | a scroller's scrollbar: its thickness (ScrollbarWidth; null: Auto), its thumb's and track's colours (CSS's scrollbar-color, inherited; null: the parent's, else the window's, Ui.scrollbarColor, and no track) |
| `break-before` | `auto`, `avoid`, `avoid-page`, `page`, `left`, `right`, `avoid-column`, `column` | paged layout (a document host's; nothing in a window): where pages may break (PageBreak; null: Auto), the named page it is on (CSS's page) |
| `break-after` | `auto`, `avoid`, `avoid-page`, `page`, `left`, `right`, `avoid-column`, `column` | paged layout (a document host's; nothing in a window): where pages may break (PageBreak; null: Auto), the named page it is on (CSS's page) |
| `break-inside` | `auto`, `avoid`, `avoid-page`, `page`, `left`, `right`, `avoid-column`, `column` | paged layout (a document host's; nothing in a window): where pages may break (PageBreak; null: Auto), the named page it is on (CSS's page) |
| `page` | Null<String> | paged layout (a document host's; nothing in a window): where pages may break (PageBreak; null: Auto), the named page it is on (CSS's page) |
| `scrollbar-color` | Null<Color> | paged layout (a document host's; nothing in a window): where pages may break (PageBreak; null: Auto), the named page it is on (CSS's page) |
| `scrollbar-track-color` | Null<Color> | paged layout (a document host's; nothing in a window): where pages may break (PageBreak; null: Auto), the named page it is on (CSS's page) |
| `outline-style` | `auto`, `solid`, `none` | whether the window's focus ring or the outline is drawn (OutlineStyle; null: Auto) |
| `ring-width` | Float | a ring around the border box (Tailwind's ring: a box-shadow of no blur, ringWidth wide, in ringColor, null: the text's; ringInset: inside), outside a gap of ringOffsetWidth in ringOffsetColor; drawn with the shadows as Tailwind composes them, the offset over the ring over the shadow, so that each comes from its own rule |
| `ring-color` | Null<Color> | a ring around the border box (Tailwind's ring: a box-shadow of no blur, ringWidth wide, in ringColor, null: the text's; ringInset: inside), outside a gap of ringOffsetWidth in ringOffsetColor; drawn with the shadows as Tailwind composes them, the offset over the ring over the shadow, so that each comes from its own rule |
| `ring-offset-width` | Float | a ring around the border box (Tailwind's ring: a box-shadow of no blur, ringWidth wide, in ringColor, null: the text's; ringInset: inside), outside a gap of ringOffsetWidth in ringOffsetColor; drawn with the shadows as Tailwind composes them, the offset over the ring over the shadow, so that each comes from its own rule |
| `ring-offset-color` | Color | a ring around the border box (Tailwind's ring: a box-shadow of no blur, ringWidth wide, in ringColor, null: the text's; ringInset: inside), outside a gap of ringOffsetWidth in ringOffsetColor; drawn with the shadows as Tailwind composes them, the offset over the ring over the shadow, so that each comes from its own rule |
| `ring-inset` | Bool | a ring around the border box (Tailwind's ring: a box-shadow of no blur, ringWidth wide, in ringColor, null: the text's; ringInset: inside), outside a gap of ringOffsetWidth in ringOffsetColor; drawn with the shadows as Tailwind composes them, the offset over the ring over the shadow, so that each comes from its own rule |
| `transform` | Null<Transform> | how the node and its subtree are drawn and hit, not laid out (Transform.parse; null: none) |
| `transform-origin` | Null<Array<Dim>> | the point the transform is about: x and y in the border box (Transform.origin; null: its centre) |
| `color` | Null<Color> | inherited from here on: null takes the parent's (the root's defaults: Style.ROOT) |
| `font-family` | Null<String> |  |
| `font-size` | Null<Float> |  |
| `font-weight` | Null<Int> | 400 regular, 700 bold |
| `italic` | Null<Bool> |  |
| `line-height` | Null<Float> | a multiple of the font size (inherited as the multiple), or pixels (lineHeightPx, CSS's line-height: 24px, inherited as the pixels; over lineHeight where a node has both, as Tailwind's leading-6 is over text-sm's) |
| `line-height-px` | Null<Float> | a multiple of the font size (inherited as the multiple), or pixels (lineHeightPx, CSS's line-height: 24px, inherited as the pixels; over lineHeight where a node has both, as Tailwind's leading-6 is over text-sm's) |
| `letter-spacing` | Null<Float> | pixels after each character, and on each space (CSS's letter-spacing, word-spacing); letterSpacingEm: a multiple of the node's font size (tracking-tight's -0.025em), inherited as the pixels it comes to, over letterSpacing where a node has both |
| `letter-spacing-em` | Null<Float> | pixels after each character, and on each space (CSS's letter-spacing, word-spacing); letterSpacingEm: a multiple of the node's font size (tracking-tight's -0.025em), inherited as the pixels it comes to, over letterSpacing where a node has both |
| `word-spacing` | Null<Float> | pixels after each character, and on each space (CSS's letter-spacing, word-spacing); letterSpacingEm: a multiple of the node's font size (tracking-tight's -0.025em), inherited as the pixels it comes to, over letterSpacing where a node has both |
| `text-align` | `left`, `center`, `right`, `justify` |  |
| `order` | Int | where it is laid out among its siblings (CSS's order: lower first, ties in the tree's order); painted and hit in that order too; Tab still follows the tree |
| `z-index` | Int | painted over its siblings with lower ones, under those with higher (and hit the other way round), whatever their order (CSS's z-index among siblings: no stacking contexts across levels) |
| `dir` | `ltr`, `rtl` | the inline direction, inherited (null: the parent's; Ltr at the root): Rtl mirrors rows, columns' cross axis, grids' columns and text's default alignment; margins, padding and offsets stay physical |
| `visibility` | `visible`, `hidden` | whether it is seen, inherited (null: the parent's; Visible at the root): Hidden keeps its place but draws, hits, focuses and shows nothing of it to assistive technology (its Visible descendants still are) |
| `pointer-events` | `auto`, `none` | whether the pointer finds it, inherited (null: the parent's; Auto at the root; CSS's pointer-events): None lets presses, hovers and the wheel through to what is under it (its Auto descendants still take them) |
| `text-wrap` | `wrap`, `no-wrap`, `balance` | whether text wraps at its box's width, inherited (null: the parent's; Wrap at the root; CSS's text-wrap-mode): NoWrap lays each line out whole, its min-content width that wide (line breaks still break); Balance wraps it into lines of about one width (TextWrap) |
| `overflow-wrap` | `normal`, `break-word`, `anywhere` | where a word too wide for its line may be cut, inherited (null: the parent's; BreakWord at the root, where CSS's is Normal: text stays in its box; CSS's overflow-wrap) |
| `word-break` | `normal`, `break-all`, `keep-all` | where lines may break inside words, inherited (null: the parent's; Normal at the root; CSS's word-break): BreakAll between letters too, KeepAll not between CJK characters |
| `font-feature-settings` | Null<String> | OpenType features, inherited, as CSS's font-feature-settings writes them ("'tnum'", "'liga' 0, 'ss01'"; null: the parent's; "normal": the default ones): their substitutions added, or liga, clig, calt and kern turned off (helder.text.FontFeature) |
| `font-variant-numeric` | Null<String> | figures' forms, inherited, as CSS's font-variant-numeric writes them ("tabular-nums", "oldstyle-nums slashed-zero"; null: the parent's; "normal"): their features (tnum, onum, zero...), under fontFeatureSettings |
| `text-transform` | `none`, `uppercase`, `lowercase`, `capitalize` | its text's letters as shown, inherited (null: the parent's; None at the root; CSS's text-transform): upper or lower case, or each word's first in upper case; a text field's own text is shown as typed |
| `text-overflow` | `clip`, `ellipsis` | a line too wide for its box (CSS's text-overflow; not inherited): Ellipsis ends it in one within the box (with NoWrap, or a word too long to break); its intrinsic widths are the whole text's |
| `max-lines` | Int | a text's lines at most (0: any), the last ending in an ellipsis when cut (CSS's line-clamp; not inherited) |
| `text-decoration` | Int | the lines drawn with the text in this node and its descendants, in this node's colour (TextDecoration's flags; 0: none; not inherited, as in CSS: it reaches the text inside) |
| `text-decoration-color` | Null<Color> | the colour of the lines textDecoration draws (null: the node's text colour; not inherited, as CSS's text-decoration-color) |
| `text-decoration-thickness` | Dim | their thickness (auto: a tenth of the font size; a percentage of it; not inherited) and an underline's place below the baseline (auto: the font's; inherited), as CSS's text-decoration-thickness and text-underline-offset |
| `text-underline-offset` | Dim | their thickness (auto: a tenth of the font size; a percentage of it; not inherited) and an underline's place below the baseline (auto: the font's; inherited), as CSS's text-decoration-thickness and text-underline-offset |
| `text-shadow` | Null<Shadow> | shadows of the text in this node and its descendants and of its decorations, under them (Shadow.parse, as CSS's text-shadow: x, y, blur and a colour, the text's without one; null: the parent's; Shadow.NONE: none) |
| `transition` | Null<Transition> | how its colours, opacity, transform and shadow ease to a new value once it has been drawn (Transition.parse, as CSS's transition; null: they jump; not inherited). While one moves, the property reads where it is; target, where it goes. |

Values: colours as CSS (`#3b82f6`, `#3b82f680`, `rgb(...)`, names), lengths in points (`{16}`, `"16"`, `"50%"`, `"auto"`), edges as CSS's shorthand (`padding="8 12"`), enums in kebab-case (`justify="space-between"`, `align-items="center"`, `direction="row"`, `position="absolute"`, `overflow="scroll"`).

## When it must run: a Haxe app with stories

Code comes after design. In the browser the studio shows a Haxe project's screens through its stories, so a code project needs at least one story file:

- `*.hx` files at the project's root; a class `implements helder.view.Markup` writes markup literals in its functions (`<view ...>...</view>`), holes `{...}` for values, signals (`helder.view.graph.Graph.signal`) for state: a signal, a memo or a function as an attribute or a child is reactive;
- `<Name>.story.hx`: `final x = story({name: "Flow/Screen", width: 420, height: 360, render: () -> ...})` (helder.story.Story): each story is a screen on the canvas, the part before `/` its row;
- a `static function main()` with `UiWindow.run(<Surface ...>...</Surface>)` is the app itself (natively; not drawn in the browser, its stories are);
- only Haxe runs in the browser (TypeScript projects run in the desktop studio);
- a build in the browser takes seconds; a change to a literal (a colour, a text, a number) is patched into the running screens without one.

helder's sign-up example (examples/signup), a card with a field, a checkbox, a switch and buttons styled by a StyleSheet, light and dark:

Signup.hx:

```haxe
// title: Sign-up card
// summary: A card of plain views styled by a StyleSheet of its own: a field, a checkbox, a switch, a badge and buttons, light and dark
// tags: ui, styles
// demo: canvas 420x360
import helder.ui.*;
import helder.ui.draw.UiWindow;
import helder.ui.draw.UiWindow.Surface;
import helder.view.*;
import helder.view.Flow.*;
import helder.view.graph.Graph.*;
import helder.view.graph.Signal;

// A card of controls made of views (each with its role, focusable, pressed
// by a click, Enter or Space), their look Signup.sheet's rules: by slot,
// state (hover, focus, data-state, data-disabled) and dark mode, its
// colours tokens with a light and a dark value. The switch turns dark
// mode on (the window's Ui.dark).
class Signup implements Markup {
	static function main() {
		var dark = signal(false);
		UiWindow.run(<Surface title="Sign up" width={420} height={360} theme={sheet} dark={dark}>{view(dark)}</Surface>);
	}

	// (the card in its sheet, light or dark, as the window shows it: Signup.story.hx's screens)
	public static function themed(dark:Bool):View {
		var d = signal(dark), root:Null<Node> = null;
		effect(() -> d(), x -> if (root?.ui != null) root.ui.dark = x);
		return <view grow={1} ref={(n:Node) -> {
			root = n;
			n.theme = sheet;
			if (n.ui != null) n.ui.dark = d.peek();
		}}>{view(d)}</view>;
	}

	public static function view(dark:Signal<Bool>):View {
		var email = signal(""), terms = signal(false);
		return <view slot="body" grow={1} padding={24} font-size={14}>
			<view slot="card">
				<view direction="row" align-items="start">
					<view grow={1} row-gap={4}>
						<text font-size={16} font-weight={600}>Create an account</text>
						<text slot="muted">Enter your email below</text>
					</view>
					<text slot="badge" font-size={12}>Beta</text>
				</view>
				<view row-gap={12}>
					<field slot="input" value={email} placeholder="m@example.com" label="Email" onInput={e -> email(e.text)}/>
					<Checkbox checked={terms} label="Accept terms"/>
					<Switch checked={dark} label="Dark mode"/>
				</view>
				<view direction="row" column-gap={8}>
					<Button variant="outline" label="Cancel"/>
					<Button label="Sign up" disabled={() -> !terms()}/>
				</view>
			</view>
		</view>;
	}

	static inline function token(name:String):Color
		return Color.parse('var(--$name)');

	public static final sheet:StyleSheet = {
		rules: [
			{slot: "body", style: {background: token("background"), color: token("foreground")}},
			{slot: "card", style: {rowGap: 24, padding: 24, radius: 12, borderWidth: 1, borderColor: token("border"), background: token("card")}},
			{slot: "muted", style: {color: token("muted")}},
			{slot: "badge", style: {padding: [2, 8], radius: 6, background: token("secondary"), fontWeight: 500}},
			{slot: "input", style: {padding: [6, 12], radius: 6, borderWidth: 1, borderColor: token("input")}},
			{slot: "input", when: ["focus"], style: {borderColor: token("muted")}},
			{slot: "input", when: ["placeholder"], style: {color: token("muted")}},
			{slot: "button", style: {padding: [8, 16], radius: 6, background: token("primary"), color: token("primary-foreground"), fontWeight: 500, cursor: Pointer}},
			{slot: "button", when: ["hover"], style: {background: Color.parse("var(--primary)/90")}},
			{slot: "button", variant: "outline", style: {background: Color.TRANSPARENT, color: token("foreground"), borderWidth: 1, borderColor: token("border")}},
			{slot: "button", variant: "outline", when: ["hover"], style: {background: token("secondary")}},
			{slot: "button", when: ["data-disabled"], style: {opacity: 0.5, cursor: Default}},
			{slot: "checkbox", style: {width: 16, height: 16, radius: 4, borderWidth: 1, borderColor: token("input"), alignItems: Center, justify: Center,
				cursor: Pointer}},
			{slot: "checkbox", when: ["data-state=checked"], style: {background: token("primary"), borderColor: token("primary"), color: token("primary-foreground")}},
			{slot: "switch", style: {width: 32, height: 18, radius: 9, padding: 2, background: token("input"), direction: Row, alignItems: Center, cursor: Pointer}},
			{slot: "switch", when: ["data-state=checked"], style: {background: token("primary"), justify: End}},
			{slot: "switch-thumb", style: {width: 14, height: 14, radius: 7, background: token("background")}},
			{slot: "switch-thumb", when: ["data-state=checked"], style: {background: token("primary-foreground")}}
		],
		light: [
			"background" => Color.rgb(0xFFFFFF), "foreground" => Color.rgb(0x0A0A0A), "card" => Color.rgb(0xFFFFFF), "border" => Color.rgb(0xE5E5E5),
			"input" => Color.rgb(0xE5E5E5), "muted" => Color.rgb(0x737373), "primary" => Color.rgb(0x171717), "primary-foreground" => Color.rgb(0xFAFAFA),
			"secondary" => Color.rgb(0xF5F5F5)
		],
		dark: [
			"background" => Color.rgb(0x0A0A0A), "foreground" => Color.rgb(0xFAFAFA), "card" => Color.rgb(0x171717), "border" => Color.rgba(0xFFFFFF, 0.1),
			"input" => Color.rgba(0xFFFFFF, 0.15), "muted" => Color.rgb(0xA1A1A1), "primary" => Color.rgb(0xE5E5E5), "primary-foreground" => Color.rgb(0x171717),
			"secondary" => Color.rgb(0x262626)
		]
	};

	static function Button(props:{label:String, ?variant:String, ?disabled:Void->Bool, ?onClick:Void->Void}):View {
		var off = () -> props.disabled != null && props.disabled();
		return <view:button slot="button" variant={props.variant} role="button" focusable={() -> !off()} disabled={off} data-disabled={off}
			onPress={_ -> if (!off() && props.onClick != null) props.onClick()}>{props.label}</view:button>;
	}

	// (a box and its label in a row: either pressed toggles it; the box named by the label)
	static function Checkbox(props:{checked:Signal<Bool>, label:String}):View {
		var toggle = () -> props.checked(c -> !c);
		var state = () -> props.checked() ? "checked" : "unchecked";
		return <view direction="row" align-items="center" column-gap={8}>
			<view:button slot="checkbox" role="checkbox" label={props.label} checked={props.checked} data-state={state} focusable onPress={_ -> toggle()}>
				<Show when={props.checked}><icon name="check" width={12} height={12}/></Show>
			</view:button>
			<text hidden cursor="pointer" onClick={_ -> toggle()}>{props.label}</text>
		</view>;
	}

	// (a track and its thumb, at the end while it is on)
	static function Switch(props:{checked:Signal<Bool>, label:String}):View {
		var toggle = () -> props.checked(c -> !c);
		var state = () -> props.checked() ? "checked" : "unchecked";
		return <view direction="row" align-items="center" column-gap={8}>
			<view:button slot="switch" role="switch" label={props.label} checked={props.checked} data-state={state} focusable onPress={_ -> toggle()}>
				<view slot="switch-thumb" data-state={state}/>
			</view:button>
			<text hidden cursor="pointer" onClick={_ -> toggle()}>{props.label}</text>
		</view>;
	}
}
```

Signup.story.hx:

```haxe
import helder.story.Story;

// The card as screens, light and dark (`helder studio examples/signup`)
final light = story({name: "Sign up/Light", width: 420, height: 360, render: () -> Signup.themed(false)});

final dark = story({name: "Sign up/Dark", width: 420, height: 360, render: () -> Signup.themed(true)});
```

More examples: https://github.com/benmerckx/helder/tree/main/examples (todo: signals, a keyed list, a text field, filters; mail). The showroom: https://helder.build/examples

## In the user's browser too

Where the browser has WebMCP (`document.modelContext`; Chrome's `chrome://flags/#enable-webmcp-testing`), the open studio registers the same tools for an agent running in that browser: `project.read {path?}`, `project.patch {path, edits | text}`, `build.check`, `run.snap {screen?}`, `run.tree {screen?}` on the open project, and `project.create {name?, files?}`, `project.list`, `project.open {name}`. The desktop studio (`helder studio <project>`) serves the first five over MCP on 127.0.0.1.