From 109dad1c76aa70f2c4c7f8d2df566d0bdc0dbb78 Mon Sep 17 00:00:00 2001
From: Developer <dev@example.com>
Date: Thu, 29 Oct 2026 19:14:57 -0500
Subject: [PATCH 1/2] feat: the formula box on CHOICES: words, sample value,
 mistakes with a fix, SHAPE and INSERT (formula box 1)

REQUIRES, each modifier's amount and USES now say the formula in words with
what it comes to for the sample character (every level at 3), worked out by a
new POST /api/systems/preview-formulas on the game's own parser. Mistakes show
in red before PUBLISH, stricter than it: a name the system hasn't got, with
USE @name for the nearest; an amount reading a formula. A formula button
(Fluent math-format icon, MIT) opens SHAPE and INSERT. The remove x is red.
Approved mockup docs/mockups/formula-box.html, 2026-10-29.
---
 CHANGELOG.md                                  |   8 +
 README.md                                     |   8 +
 .../system_builder_formula_preview.test.js    | 120 +++++++++++++
 backend/routes/systems.js                     |  13 ++
 backend/systemBuilder/formulaPreview.js       | 103 +++++++++++
 e2e/COVERAGE.md                               |   1 +
 e2e/README.md                                 |   1 +
 e2e/tests/builder-clicks.spec.ts              |   3 +
 e2e/tests/builder-formula-box.spec.ts         |  72 ++++++++
 frontend/src/components/ChoicesPage.tsx       |  16 +-
 frontend/src/components/FeaturesEditor.tsx    |  60 +++++--
 frontend/src/components/FormulaIcon.tsx       |  13 ++
 .../hooks/__tests__/useFormulaBox.test.tsx    | 118 ++++++++++++
 frontend/src/hooks/useFormulaBox.tsx          | 170 ++++++++++++++++++
 .../src/sheets/__tests__/formulaBox.test.ts   | 119 ++++++++++++
 frontend/src/sheets/builderHelp.ts            |   6 +-
 frontend/src/sheets/formulaBox.ts             | 139 ++++++++++++++
 frontend/src/sheets/systemsApi.ts             |   4 +
 18 files changed, 948 insertions(+), 26 deletions(-)
 create mode 100644 backend/__tests__/system_builder_formula_preview.test.js
 create mode 100644 backend/systemBuilder/formulaPreview.js
 create mode 100644 e2e/tests/builder-formula-box.spec.ts
 create mode 100644 frontend/src/components/FormulaIcon.tsx
 create mode 100644 frontend/src/hooks/__tests__/useFormulaBox.test.tsx
 create mode 100644 frontend/src/hooks/useFormulaBox.tsx
 create mode 100644 frontend/src/sheets/__tests__/formulaBox.test.ts
 create mode 100644 frontend/src/sheets/formulaBox.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c8859d8e..c86c337e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,6 +53,14 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- **Formulas on CHOICES say what they do, and help you write them.** Under a modifier's amount, a
+  feature's USES and an option's REQUIRES, a line now says the formula in words with what it comes
+  to for the sample character: "+2 for each level · sample Level 3: +6", "needs Strength 13 or
+  more · the sample (Strength 16) meets it". A mistake shows in red before you publish, including a
+  name the system hasn't got: `@lvl` offers USE @level to fix it. The new formula button beside each
+  box opens SHAPE, which writes common ones for you (A NUMBER, PER LEVEL, PER CLASS LEVEL, HALF
+  LEVEL; AT LEAST and LEVEL AT LEAST on a requirement), and INSERT, the names the box can read, put
+  where your cursor is. The × that removes a modifier is now red.
 - **Features that add to the token's maximum (7a5a3).** A feature whose modifier is on HP MAX (or
   WOUNDS, under a wound count) now moves the token's real maximum, not just the number the sheet
   names: a level 3 fighter picking Tough (`2 * @level`) goes from 20 to 26 of 26, the current
diff --git a/README.md b/README.md
index 58f97a86..58728891 100644
--- a/README.md
+++ b/README.md
@@ -449,6 +449,7 @@ CITY_NET/
 │   │   ├── choices.js          # A system's choices (7a1a; approved mockup builder-choices, 2026-10-27): the lists a character picks from (classes, backgrounds, feats), each named one and many, picked once, so many times or any, levelled or not, and MORE THAN ONCE for multiclassing; options with an optional requirement (a formula) and features, each unlocking at a level in a levelled list and doing any of: modifiers on a stat, formula or health field, uses refilled by a rest, rolls it gives, a change it lets a roll take, another list to pick from, or only words. Option and feature ids share one set; an option's level is read as @<option>_level, so that name must be free. A character's picks (7a1b) are kept on their sheet under _choices, which players never write as a field (sheets/templates.js), and read keeping only what holds; their levels (@soldier_level, a levelled list's sum @classes_level, and @level unless the system has its own), the features unlocked by level, and overlayOf: each stat with its modifiers and each formula's modifiers, worked out on every save and never written into a stat, so a pick taken away takes its effects with it. A modifier's amount reads the sheet as typed and levels, never a formula. Rolls (tableRolls.js) and PUBLISH's preview (versionDiff.js) read the same numbers. At the table (7a3a): spent uses kept under _uses; every save writes _worked (workedOf: picks, levels, where each change comes from, uses left, options not met); requirements met or not on the sheet as it reads, and in words (INTELLECT >= 13); choicesShown, the lists as the sheet draws them, never a formula
 │   │   ├── choicesImport.js    # A list's options and features read from a file (choices import 1; approved mockup choices-import, 2026-10-28): `[options]` and `[features]` rows matched by name against the draft, nothing deleted; an empty cell leaves a part, `-` clears it; a feature found by level too only when its name repeats; a line with a mistake skipped and named by its line; only words, levels, requirements and uses read. Returns the list as it would be and what changes; saves nothing
 │   │   ├── tokenMax.js         # A feature's modifier on the token's maximum (7a5a3; decision 10 of the approved mockup nested-choices): Tough's `2 * @level` put on the token's real HP MAX or WOUNDS while the pick counts and taken off when it doesn't, the current moving with it; the sheet keeps what it added and to which token, so a second save adds nothing and a new token starts clean; after any sheet change, and every player's when a new version of the running game is published
+│   │   ├── formulaPreview.js   # The builder's formula box (formula box 1; approved mockup formula-box, 2026-10-29): a modifier's amount, a requirement or a feature's uses read by the game's own parser for the sample character (every level at 3), with each name it reads and its value; or its mistake, stricter than PUBLISH: a name the system hasn't got (with the nearest real one) and an amount reading a formula. POST /api/systems/preview-formulas
 │   │   ├── conditions.js       # A system's conditions: the standard set every system starts with (Blinded, Bleeding, Poisoned... ten in all), each renamed, described, given modifiers and an end (when removed, after rounds, or at the rests it names) or turned off, and the system's own, up to 60 in all. A definition stores only its changes; conditionsOf gives each one whole. Icons are one of 24 drawn for CITY_NET or an uploaded picture; modifiers name a stat, a formula or all rolls, one on all rolls reaching every roll of the system's own (tableRolls.js); any condition may wait on a house rule
 │   │   ├── diceFaces.js        # A system's own dice (6c1a): symbols (a name, a mark of a character or two or one of the condition icons, what each cancels as a pair, what it also counts as, one step) and dice whose faces show a signed number, symbols, both or nothing (2 to 100 faces, a danger color for a bad die); checked as an untrusted file is, read whole for the rolls (symbolsOf, diceOf); a symbol's look (6c2b1): its mark, a drawn or uploaded icon (as a condition's), or a 16 by 16 drawing kept in the system (16 rows of 4 hex digits), one picture at a time
 │   │   ├── rollStyles.js       # A custom system's own rolls (Phase 6): dice of any size, Fate dice and named dice, counts worked out from the character; read as a sum, the highest or lowest kept, or successes counted; formula text added, a target met over or under, bands read like a lookup table; exploding dice and naturals; matched dice (a pair of 10s adding successes, doubles), ones that cancel successes, glitches (and the worse one with nothing succeeding), a named die's own effect (Messy, Bestial), and the zero-dice rule; the changes a player picks before rolling (advantage and disadvantage cancelling, a push, a bonus) with what each costs, taken from a stat or added to one (Blades' push adds 2 Stress); CP:R's exploding-and-imploding first die; and the presets the builder starts from (D&D, PbtA, Blades, Vampire, Fate, CWN, CP:R, SR6); the system's `rolls` section checked (up to 60, different ids, ROLLED BY stats, stats groups and formulas it has, its tables callable). Each roll checked in the builder's words; dice only from the source handed in (the server's secure one at the table). A system's own dice (6c1b): a kind of dice may be one of them, landing on one of its faces, its number (0 for none) what every rule reads; COUNT THE SYMBOLS counts the kept dice's symbols (one that also counts as another counted as both), cancels each pair one for one, and reads what is left of `on` (or the numbers); every check against the system's own dice and symbols
@@ -614,6 +615,7 @@ CITY_NET/
 │       ├── system_builder_choices_numbers.test.js # What picks do to a character's numbers: picks read from the sheet keeping only what holds (a known option, once, within what the list allows, MORE THAN ONCE for multiclassing, levels from 1 to the highest); each option's level, a list's sum and @level, a system's own level left alone; features unlocked by level; on a save, a stat's modifier reaching the formulas reading it while the stat stays as typed, a formula's added before what reads it, amounts from levels, a pick taken away taking its effects; an amount reading a formula refused, a list's sum name kept free; rolls reading the same numbers; PUBLISH's preview showing a feature changed; the picks never a player's to write
 │       ├── system_builder_nested_choices.test.js # Lists inside lists (7a5a1): PICKED and HOW MANY checked, loops through other lists named; a pick under a feature counting while it is unlocked and has room, kept waiting when it locks, deeper lists in any order, a list picked both ways counting its own apart, picks a list's way no longer counts kept; only what counts reaching the numbers; what the sheet is told; picking under a feature and every refusal
 │       ├── system_builder_token_max.test.js # A feature on the token's maximum (7a5a3): its bonus summed and never added to the sheet twice; the token moved by what changed since the sheet last said, a new token clean; at the table a pick, a level and a drop moving the maximum and current (never below 0, never over the maximum), a stat the bonus reads changed by the player, the GM's sheet route or an import; nothing without a token, with token health off or in a game not running; a new version published
+│       ├── system_builder_formula_preview.test.js # Level formulas at the sample level, stats, formulas, tables and functions read, a name the system hasn't got with the nearest (a tie to the first), an amount reading a formula refused but a level with a formula's id allowed, what doesn't read, empty, no levels without a levelled list, at most 20 a request; the route, main admin only
 │       ├── system_builder_picking.test.js # Picking: a player's pick (room, not twice, a requirement in words), never a drop, their own levels and spent uses within bounds; the GM past a requirement but not past room, and taking a pick away; every save writing the picks, levels, where each change comes from, uses and what isn't met (none for a system without choices); the lists as the sheet draws them, never a formula; a rest refilling the uses it or what it counts as refills; no _ name a player's to write; through the socket as a player (their own only, told why not, nothing written) and as the GM (on the player named)
 │       ├── system_builder_citysys_zip.test.js # Sharing with pictures: the uploads a system names and where a symbol shows, left out cleanly (a mark for a bare symbol), a zip made and read back, a picture missing from disk left out, one shared picture; a zip someone sent refused when broken, empty, too large or holding two systems, nothing unpacked outside its places, past an upload's size or past the count (a broken entry proves it), and only named pictures stored; through the routes: the count listed, ?images=1 a zip, otherwise the .citysys without, a zip installed on a server without its pictures, nothing stored when refused, GM only
 │       ├── system_builder_words.test.js # Every term in every form resolved for the builder; only the terms a system renamed sent with its sheet; the server's own text, the starter sheet and a one-pool HEALTH folder using a system's word only where it chose one
@@ -815,6 +817,7 @@ CITY_NET/
 │   │   │   ├── HouseRulesPage.tsx       # HOUSE RULES: a system's own house rules down the left with how each starts, up to 20 (+ RULE opens the new one); the open one's name, what it means and STARTS ON or OFF with their "?", what waits on it with GO TO, and DELETE asking first, saying what stays
 │   │   │   ├── ChoicesPage.tsx          # CHOICES (7a2b1; approved mockup builder-choices, 2026-10-27): the lists a character picks from down the left; the open list with ONE / MANY, A CHARACTER PICKS (ONE, SEVERAL with how many, ANY), MORE THAN ONCE and LEVELLED, a line saying what the list now means (with @<list>_level when levelled), and its options; the open option with its name, words and an optional requirement, its level name in a levelled list, and its features (FeaturesEditor.tsx). DELETE asks first, saying what goes; a "?" beside every setting
 │   │   │   ├── ChoicesImport.tsx        # IMPORT on a CHOICES list (choices import 2; approved mockup choices-import, 2026-10-28): over the list and option columns, DOWNLOAD THIS LIST and DOWNLOAD EXAMPLE, a file pasted or uploaded, PREVIEW read by the server, mistakes warned of by line (named at the top as links that select the line, marked in the line numbers beside the text), APPLY into the draft only for the text previewed
+│   │   │   ├── FormulaIcon.tsx          # The formula box's button mark: "math format professional" from Microsoft's Fluent UI System Icons (MIT), picked by the user 2026-10-29, drawn in the text's color so it follows the theme
 │   │   │   ├── FeaturesEditor.tsx       # An option's features on CHOICES (7a2b2): grouped by the level each unlocks at in a levelled list, each row tagged with what it does (MODIFIER, USES, ROLL, CHANGE, CHOICE, TEXT); the open one with its name, AT LEVEL (set when the box is left or on Enter, so typing 12 never moves it to 1 on the way), words, modifiers (what each changes, grouped stats / formulas / health, and by how much), uses and the rest that refills them, rolls it gives, roll changes it lets the character take, and a list it opens; DELETE FEATURE asks first; a "?" beside every setting
 │   │   │   ├── PublishPreviewPage.tsx   # What PUBLISH shows first from v2 on, in place of the open page: what the new version changes BY CHANGE (each line with who it reaches and their own value, or the SAMPLE), BY CHARACTER when someone plays it, KEPT on what stops showing, NOTHING CHANGES FOR ANY CHARACTER when so, the one line for the rest, BACK TO EDITING and PUBLISH vN (not while the draft has problems)
 │   │   │   ├── ConditionIcon.tsx        # A condition's icon: one drawn for CITY_NET, stroked in the theme's color, or an uploaded picture through <img> only; anything unknown draws the target
@@ -1011,6 +1014,7 @@ CITY_NET/
 │   │   │   ├── useEnemyVehicles.ts # The GM's enemy vehicles, and the tokens on the map level that could fill their seats. Asked for rather than pushed, and refused to anyone but the GM — so a player's client never holds enemy pools or armour at all, which is what keeps "what may players see" from being a question the feature has to answer
 │   │   │   ├── useVehicleRoster.ts # Every vehicle in play and who is in which seat. Held outside the window because the buttons that open it need to know whether the table owns a vehicle at all — one subscription, so the two cannot disagree. Takes the socket ref, not its current value: a ref is not reactive, and reading it before the socket exists binds to nothing forever
 │   │   │   ├── useFormulaInsert.ts # INSERT for formulas: where the cursor last was, in which box (a formula's text or a condition's IF, THEN or ELSE), and a name put there; FORMULAS and the node panel share it
+│   │   │   ├── useFormulaBox.tsx  # The formula box (formula box 1; approved mockup formula-box, 2026-10-29): a formula's text with a FORMULA button (FormulaIcon.tsx), given to the page as the box and the help under its row; under it, always, the formula in words with the sample's value, or its mistake in red with USE @name; the button alone opens SHAPE (a common formula written from a number and a name) and INSERT (names put at the cursor). On CHOICES: REQUIRES, each modifier's amount (the × beside it red), USES
 │   │   │   ├── usePreviewValues.ts # A draft's formulas worked out by the server for its sample character a moment after editing stops, and with each house rule an alternative follows on: FORMULAS and the graph view show the same values; the graph view asks with the house rules TRY ON THE MAP has on
 │   │   │   ├── usePlayerSheet.ts   # Shared sheet state, debounced saves, house-rule flags, action emitters (roll/deathSave/stabilize/castSpell); used by CharacterSheetWindow and SheetPage
 │   │   │   └── __tests__/
@@ -1022,6 +1026,7 @@ CITY_NET/
 │   │   │       ├── useTrayNotify.test.ts  # The tray's bell starts ON, takes the account's choice and saves a change as trayNotify, kept apart from the tray's motion under its own names, a choice it doesn't have ignored
 │   │   │       ├── useRollFlash.test.ts   # Someone else's roll while the tray is shut flashes it, not your own nor with the bell off nor with the tray open; stops as the tray opens, which still opens on the history; forgotten once shut; one stable handler reading the tray and bell as they are now
 │   │   │       ├── useChoicesRefused.test.tsx # The server's refusal of a pick shown, a new one starting the clock again, gone after; the listener taken off on unmount; nothing without a socket (7a3b2)
+│   │   │       ├── useFormulaBox.test.tsx # The words, then the server's sample value; nothing asked of an empty box; a mistake in red, the box marked, USE @name fixing it; an answer for older text never shown; SHAPE and INSERT only by the button; shapes written and rewritten; a requirement on a stat; INSERT at the cursor
 │   │   │       ├── useVehicleRoster.test.tsx             # Binds when the socket turns up, empties on a system switch, re-asks on a sheet save
 │   │   │       ├── useVideoMapTexture.test.ts            # Every assertion is a silent failure: an unmuted video never starts, a hidden tab keeps decoding, a released map keeps its buffers, and a browser that refuses autoplay leaves a still frame with no explanation
 │   │   │       ├── usePlayerSheet.save.test.tsx          # Edits held 400ms so typing is one save, and anything still waiting sent rather than dropped when the sheet goes away
@@ -1101,6 +1106,7 @@ CITY_NET/
 │   │   │   ├── houseRules.ts       # HOUSE RULES as logic: a system's own house rules (up to 20, a new one starting off), changed keeping their ids, deleted leaving what waited on them always there (no part, section or condition waits on it, a formula loses its alternative), and what waits on a rule with the page GO TO opens; the draft as it would be worked out with one rule on, or as the game would run it with a set of rules on (the server's withHouseRules mirrored, held to it); the rules a running game has on (useHouseRules) and the boxes changed from them; held to the server's checks
 │   │   │   ├── choices.ts         # CHOICES as logic (7a2b1): a system's lists and their options read, made (named to rename, ids free of every option's, feature's and level name's), changed (one pick, not levelled and not again store nothing; several capped) and removed (a list taking with it any feature opening it; an option from its own list only), and the level names formulas read; an option's features (7a2b2) made at a level, changed (blank words, level 1 or any level outside a levelled list, empty lists, no uses and no list store nothing; a level past the highest is the highest) and removed, what each does as tags, and what a feature can name: the stats, formulas and health fields, every rest (the off ones said so), the rolls and their changes. Mirrors backend choices.js, every edit held to its checks
 │   │   │   ├── choicesImport.ts   # IMPORT as logic (choices import 2): DOWNLOAD EXAMPLE made from the system (its @names, its rests by name, a level column only for a levelled list, made-up rows) and DOWNLOAD THIS LIST (cells quoted as a spreadsheet would, rests by name where the reader finds them so, a # note for what a feature does beyond words and uses), a previewed list put into the draft, a line to select, and changes in the page's words
+│   │   │   ├── formulaBox.ts      # The formula box as logic (formula box 1): a formula in words (+2 for each level, needs Strength 13 or more), its sample line, INSERT's groups (no formulas for an amount), and the SHAPES with why one can't be used yet and what each writes (a name at the cursor is statsRules.ts' insertToken)
 │   │   │   ├── choicesShown.ts    # The CHOICES block as logic (7a3b1): the lists in words from the render copy, the character's picks, levels, uses and what isn't met from the sheet's worked-out view (_worked) read safely; each list as drawn (picks with levels, unlocked features by level, the next to come, room, what's left to pick and what it needs, the total and its breakdown), a use pip's click, and what a feature does in a few words. Works no number out: the server does. choiceEffects (7a3b2): what the picks do to each field, for the sheet's badge (a stat as typed and with its bonuses, a formula as saved and without them, each bonus named), from what the server says each modifier came from
 │   │   │   ├── builderHelp.ts      # Every word of the builder's help in one place: the first-time tour (welcome, then the rail SETUP to PUBLISH), the HELP page's topics (getting started, every page with GO TO, formulas, THE MAP (GRAPH: nodes and wires, + ADD, CUT, diamonds, notes, groups, UNDO, PROBLEMS, TRY ON THE MAP), dice, health models, sharing and versions, who sees the target, the examples to open) and the formula reference, held to the engine's own functions by a test; and the words of the "?" beside each setting, by page. The tour's STATS & RULES step points to HOUSE RULES and the map, and CHOICES has a step of its own (nine since 2026-10-28)
 │   │   │   ├── versionPreview.ts   # What PUBLISH would change, as the builder says it: each change the server names in words (KEPT where something stops showing), grouped BY CHANGE with who it reaches and their own value (or the SAMPLE when nobody plays it; a number moving because a formula it reads changed gets its own line), BY CHARACTER, the one line for what touches no character, the heading and the line under it; HOUSE RULES as a group, and a formula's alternative apart from its own change
@@ -1143,6 +1149,7 @@ CITY_NET/
 │   │   │       ├── houseRules.test.ts           # The house rules list, a new one up to twenty, a rule changed (blank description and starting off store nothing), deleted with everything under it freed and nothing else touched, and what waits on a rule by page; a part, condition and section put under a rule and out again; the rules a running game has on and only changed boxes sent; the draft as the game would run it equal to the server's, rule for rule; every edit taken by the server's checks
 │   │   │       ├── choices.test.ts               # Held to the server: the same limits, and every edit leaving a system its checks take; lists read, made up to the limit, picks / levelled / again stored only when they say something, names kept as typed, removed with no feature left opening them; options made with free ids (a formula's @x_level too), changed with empty words storing nothing and features kept, removed from their own list alone; level names as the server reads them
 │   │   │       ├── choicesImport.test.ts         # Held to the server's reader: this list downloaded and imported back changes nothing (commas, quotes, #, spacing, line breaks), the example reads without a mistake and leaves a system the server takes, levelled or not, with no stats or rests; file names, line ranges, change wording
+│   │   │       ├── formulaBox.test.ts            # Amounts, uses and requirements in words, by label or as written; the sample line; INSERT's groups and levels; each shape, what it writes and why it can't be used yet
 │   │   │       ├── choicesShown.test.ts          # Held to the server's own choicesShown and workedOf: the worked-out view read (empty for none or junk); each pick's level, unlocked features and the next; levels added up and said how; what's left, one not met saying what it needs; room; an option gone left out; pips spending and taking back; what a feature does in words; the badge's numbers for a stat and a formula, each bonus named, nothing for a field not shown (7a3b2)
 │   │   │       ├── builderHelp.test.tsx         # The help held to the builder: the tour down the rail, a topic for every page, every health model and built-in example, every formula function the engine knows with its arguments and an example it reads; the "?" shown on hover and focus, gone after, placed where it fits; each setting's words a sentence filed by its page; a setting's name tied to its field, the "?" outside it; the tour nine steps since CHOICES, each named as the rail names its page, STATS & RULES pointing to HOUSE RULES; a column header named by its word, the "?" inside it
 │   │   │       ├── versionPreview.test.ts       # The version preview's words, held to the server's own comparison (every change it names has words, every one-line section a name), BY CHANGE and BY CHARACTER on real answers, the SAMPLE, a field changed two ways, and the heading; house rules and alternatives in words, grouped, a value under the alternative that moves it
@@ -1280,6 +1287,7 @@ CITY_NET/
 │       ├── sheet-choices.spec.ts   # A custom system's CHOICES block at the table (7a3b1): a player's class not met off with what it needs, SOLDIER picked with its features and its bonus on Defense, raised to level 2 unlocking the next feature, a use ticked off and given back by a short rest the GM calls; as the server keeps it; the GM on their own sheet adding an option not met, the bonus named on Defense, and a pick taken away, asked first (7a3b2)
 │       ├── sheet-nested-choices.spec.ts # Lists inside lists (7a5a2): in the builder SPECIALTIES (OPENED BY the Soldier's Specialty) set THROUGH FEATURES and COMMONS EVERYONE HAS IT; at the table a specialty picked under the feature at level 3, kept waiting at 2, back at 3; COMMONS every character's, its Improvement at level 2
 │       ├── sheet-token-max.spec.ts # A feature on the token's maximum (7a5a3): a FIGHTER at level 3 picks TOUGH and the token goes from 20 to 26 of 26, the sheet naming the bonus and MAX HEALTH following; a level down, 24; the GM drops TOUGH from the player's sheet and it is back at 20
+│       ├── builder-formula-box.spec.ts # The formula box (formula box 1): a misspelt name in red and USE @level, the words with the sample's value, PER CLASS LEVEL and an INSERT name, AT LEAST on REQUIRES, saved as written with no problems
 │       ├── sheet-visibility.spec.ts # Who sees what on a customized sheet: the owner (the GM's field read-only), another player looking them up from GLOBAL_CHAT (public lines only, nothing else sent), the GM opening the whole sheet the same way and setting the GM's field (coverage family 1)
 │       └── builder-smoke.spec.ts   # The GM signs in, opens the System Builder, meets and skips the first-time tour (reset first), finds MY SYSTEMS, and goes back to the map
 ├── Dockerfile.backend
diff --git a/backend/__tests__/system_builder_formula_preview.test.js b/backend/__tests__/system_builder_formula_preview.test.js
new file mode 100644
index 00000000..fb96b9ac
--- /dev/null
+++ b/backend/__tests__/system_builder_formula_preview.test.js
@@ -0,0 +1,120 @@
+/**
+ * The builder's formula box (formula box 1; approved mockup docs/mockups/formula-box.html,
+ * 2026-10-29): a modifier's amount, a requirement or a feature's uses read as the game reads it,
+ * worked out for the sample character with every level at 3, or its mistake said before PUBLISH:
+ * one that doesn't read, a name the system hasn't got (with the nearest real one), and an amount
+ * reading a formula.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import jwt from 'jsonwebtoken';
+import { createRequire } from 'module';
+import { makeTestDb } from './helpers/testDb.js';
+
+process.env.JWT_SECRET = 'test-secret';
+const require_ = createRequire(import.meta.url);
+const { previewFormula, previewFormulas, SAMPLE_LEVEL, MOST, nearest } = require_('../systemBuilder/formulaPreview');
+const { elevatedUsers } = require_('../middleware/auth');
+const systemsRoute = require_('../routes/systems.js');
+
+const GM = jwt.sign({ id: 1, username: 'gm', role: 'admin', isTemporary: false }, 'test-secret');
+const EDITOR = jwt.sign({ username: 'ghost', isTemporary: true }, 'test-secret');
+
+const DEF = {
+  format: 1,
+  name: 'Hearth',
+  stats: [{ id: 'abilities', label: 'ABILITIES', stats: [{ id: 'str', label: 'Strength' }, { id: 'con', label: 'Constitution' }] }],
+  samples: { str: 16, con: 14 },
+  lookups: { mod: { bands: [{ upTo: 9, value: -1 }, { upTo: 13, value: 0 }, { value: 2 }] } },
+  derived: [{ id: 'con_mod', label: 'CON modifier', formula: 'mod(@con)' }],
+  core: { health: { model: 'pool' } },
+  choices: [
+    { id: 'classes', one: 'Class', many: 'Classes', levelled: true, options: [{ id: 'fighter', label: 'Fighter', features: [] }] },
+  ],
+};
+
+describe('a formula read for the box', () => {
+  it('works out a level formula with every level at the sample level, saying each name it reads', () => {
+    expect(SAMPLE_LEVEL).toBe(3);
+    expect(previewFormula(DEF, '2 * @level', 'amount')).toEqual({ ok: true, value: 6, reads: [{ id: 'level', label: 'Level', value: 3 }] });
+    expect(previewFormula(DEF, '@fighter_level + @classes_level', 'amount').value).toBe(6);
+  });
+
+  it('reads the sample\'s stats, its formulas worked out, tables and functions', () => {
+    expect(previewFormula(DEF, '@str', 'amount')).toEqual({ ok: true, value: 16, reads: [{ id: 'str', label: 'Strength', value: 16 }] });
+    expect(previewFormula(DEF, '@con_mod + 1', 'uses')).toEqual({ ok: true, value: 3, reads: [{ id: 'con_mod', label: 'CON modifier', value: 2 }] });
+    expect(previewFormula(DEF, 'floor(@level / 2) + mod(@str)', 'amount').value).toBe(3);
+    expect(previewFormula(DEF, '@str >= 13', 'requires').value).toBe(1);
+    expect(previewFormula(DEF, '@con >= 15', 'requires').value).toBe(0);
+  });
+
+  it('says a name the system hasn\'t got, and the nearest real one when there is one', () => {
+    expect(previewFormula(DEF, '2 * @lvl', 'amount')).toEqual({ ok: false, problem: "@lvl isn't one of this system's names", name: 'lvl', suggest: 'level' });
+    expect(previewFormula(DEF, '@strenght', 'requires')).toEqual({ ok: false, problem: "@strenght isn't one of this system's names", name: 'strenght' });
+    expect(nearest('fightr_level', ['fighter_level', 'level'])).toBe('fighter_level');
+    // A tie goes to the first named.
+    expect(nearest('lvel', ['level', 'lvl'])).toBe('level');
+  });
+
+  it('refuses an amount reading a formula, as PUBLISH does, but not a requirement or uses', () => {
+    expect(previewFormula(DEF, '@con_mod', 'amount')).toEqual({ ok: false, problem: '@con_mod is a formula: an amount reads stats as typed and levels' });
+    expect(previewFormula(DEF, '@con_mod', 'requires').ok).toBe(true);
+    expect(previewFormula(DEF, '@con_mod', 'uses').ok).toBe(true);
+  });
+
+  it('lets an amount read a level even where a formula has the same id', () => {
+    const both = { ...DEF, derived: [...DEF.derived, { id: 'classes_level', formula: '1' }] };
+    expect(previewFormula(both, '@classes_level', 'amount')).toMatchObject({ ok: true, value: 3 });
+  });
+
+  it('says what doesn\'t read, and that an empty box is empty', () => {
+    expect(previewFormula(DEF, '2 * (@level', 'amount')).toMatchObject({ ok: false });
+    expect(previewFormula(DEF, '2 * (@level', 'amount').problem).not.toBe('Empty');
+    expect(previewFormula(DEF, '  ', 'amount')).toEqual({ ok: false, problem: 'Empty' });
+    expect(previewFormula(DEF, 'nope(1)', 'amount').ok).toBe(false);
+  });
+
+  it('has no levels without a levelled list', () => {
+    const flat = { ...DEF, choices: [] };
+    expect(previewFormula(flat, '@level', 'amount')).toMatchObject({ ok: false, problem: "@level isn't one of this system's names" });
+  });
+
+  it('reads at most MOST formulas a request, a kind it doesn\'t know as a requirement', () => {
+    const many = Array.from({ length: MOST + 5 }, () => ({ text: '1', kind: 'amount' }));
+    expect(previewFormulas(DEF, many)).toHaveLength(MOST);
+    expect(previewFormulas(DEF, [{ text: '@con_mod', kind: 'nonsense' }])[0].ok).toBe(true);
+    expect(previewFormulas(DEF, 'not a list')).toEqual([]);
+  });
+});
+
+describe('the route', () => {
+  let app;
+  beforeEach(async () => {
+    elevatedUsers.add('ghost');
+    const db = await makeTestDb();
+    app = express();
+    app.use(express.json());
+    app.use('/api/systems', systemsRoute(db));
+  });
+  afterEach(() => elevatedUsers.delete('ghost'));
+  const post = (body, token = GM) => request(app).post('/api/systems/preview-formulas').set({ Authorization: `Bearer ${token}` }).send(body);
+
+  it('reads each formula against the draft sent', async () => {
+    const res = await post({ definition: DEF, formulas: [{ text: '2 * @level', kind: 'amount' }, { text: '@lvl', kind: 'amount' }] });
+    expect(res.status).toBe(200);
+    expect(res.body.sampleLevel).toBe(3);
+    expect(res.body.results.map((r) => r.ok)).toEqual([true, false]);
+    expect(res.body.results[0].value).toBe(6);
+  });
+
+  it('refuses a draft it can\'t read at all', async () => {
+    expect((await post({ definition: 'nope', formulas: [] })).status).toBe(400);
+  });
+
+  it('is the main admin\'s alone', async () => {
+    expect((await post({ definition: DEF, formulas: [] }, EDITOR)).status).toBe(403);
+    expect((await request(app).post('/api/systems/preview-formulas').send({ definition: DEF })).status).toBe(401);
+  });
+});
diff --git a/backend/routes/systems.js b/backend/routes/systems.js
index c4e807ba..ea50b26c 100644
--- a/backend/routes/systems.js
+++ b/backend/routes/systems.js
@@ -14,6 +14,7 @@ const { buildCustomTemplate } = require('../sheets/pdfTemplate');
 const runtime = require('../systemBuilder/runtime');
 const { checkDefinition, NEW_SYSTEM_SEEN } = require('../systemBuilder/definition');
 const { previewDerived } = require('../systemBuilder/derived');
+const { previewFormulas, SAMPLE_LEVEL } = require('../systemBuilder/formulaPreview');
 const tableRolls = require('../systemBuilder/tableRolls');
 const { conditionsOf } = require('../systemBuilder/conditions');
 const { diceOf } = require('../systemBuilder/diceFaces');
@@ -288,6 +289,18 @@ module.exports = (db, io = null) => {
     res.json(previewDerived({ lookups: definition.lookups, derived: definition.derived }, samples));
   });
 
+  /**
+   * The builder's formula box (formula box 1): up to 20 formulas, `{ text, kind }` each (a
+   * modifier's amount, a requirement, a feature's uses), each read against a draft as the game
+   * reads it: its mistake, or its value for the sample character with each name it reads.
+   */
+  router.post('/preview-formulas', gm, (req, res) => {
+    const { definition, formulas } = req.body || {};
+    const checked = checkDefinition(definition);
+    if (checked.fatal) return res.status(400).json({ error: checked.fatal });
+    res.json({ results: previewFormulas(definition, formulas), sampleLevel: SAMPLE_LEVEL });
+  });
+
   /**
    * TEST ROLL (6b1a; approved mockup docs/mockups/builder-rolls.html): one of a draft's rolls, unsaved
    * changes and all, made for its sample character (its samples, and its formulas worked out on
diff --git a/backend/systemBuilder/formulaPreview.js b/backend/systemBuilder/formulaPreview.js
new file mode 100644
index 00000000..89f0d5bc
--- /dev/null
+++ b/backend/systemBuilder/formulaPreview.js
@@ -0,0 +1,103 @@
+// One formula as the builder's formula box shows it (formula box 1; approved mockup
+// docs/mockups/formula-box.html, 2026-10-29): read by the game's own parser, its mistake said
+// before PUBLISH, or worked out for the sample character, with each name it reads and that name's
+// value, so the box can say it in words (+2 for each level · sample Level 3: +6).
+//
+// Stricter than publishing, which only asks that a formula reads: a name the system hasn't got
+// (@lvl) quietly counts as 0 at the table, so here it is a mistake, with the nearest real name. A
+// modifier's amount reads the sheet as typed and the levels, never a formula (choices.js), so one
+// reading a formula is the same mistake PUBLISH refuses.
+//
+// The sample character has stats only (stats.js `samples`); every level name reads SAMPLE_LEVEL,
+// so a formula on levels shows something worth reading.
+
+const { parse, evaluate, references } = require('./expression');
+const { ruleValue } = require('./rules');
+const { tablesOf, lookupIn, previewDerived } = require('./derived');
+const { namesOf, levelNamesOf } = require('./choices');
+
+/** What every level name reads for the sample character. */
+const SAMPLE_LEVEL = 3;
+/** What a formula box holds: a modifier's amount, an option's requirement, a feature's uses. */
+const KINDS = new Set(['amount', 'requires', 'uses']);
+/** The most formulas one request reads. */
+const MOST = 20;
+
+const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+/** How many single-letter changes turn `a` into `b`. */
+const distance = (a, b) => {
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i += 1) {
+    let diagonal = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const above = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diagonal = above;
+    }
+  }
+  return row[b.length];
+};
+
+/** The known name nearest `name`, two changes at most, or null. */
+const nearest = (name, known) => {
+  let best = null;
+  let bestAt = 3;
+  for (const k of known) {
+    const d = distance(name, k);
+    if (d < bestAt) { best = k; bestAt = d; }
+  }
+  return best;
+};
+
+/** The sample character as formulas read it: its stats, its formulas worked out, every level at SAMPLE_LEVEL. */
+const sampleOf = (definition) => {
+  const samples = isPlainObject(definition.samples) ? definition.samples : {};
+  const { values } = previewDerived({ lookups: definition.lookups, derived: definition.derived }, samples);
+  const levels = Object.fromEntries([...levelNamesOf(definition)].map((n) => [n, SAMPLE_LEVEL]));
+  return { ...samples, ...values, ...levels };
+};
+
+/**
+ * One formula read against `definition`: `{ ok: false, problem, suggest? }` when it can't be used,
+ * else `{ ok: true, value, reads }`, `reads` naming each @name it reads with its label and value.
+ */
+const previewFormula = (definition, text, kind, sample = sampleOf(definition)) => {
+  if (typeof text !== 'string' || !text.trim()) return { ok: false, problem: 'Empty' };
+  const tables = tablesOf(isPlainObject(definition.lookups) ? definition.lookups : undefined);
+  const isTable = (name) => own(tables, name);
+  let tree;
+  try { tree = parse(text, isTable); } catch (e) { return { ok: false, problem: e.message }; }
+  const names = namesOf(definition);
+  const fields = [...references(tree).fields];
+  const unknown = fields.find((n) => !names.has(n));
+  if (unknown) {
+    const suggest = nearest(unknown, names.keys());
+    return { ok: false, problem: `@${unknown} isn't one of this system's names`, name: unknown, ...(suggest ? { suggest } : {}) };
+  }
+  if (kind === 'amount') {
+    const formulas = new Set((Array.isArray(definition.derived) ? definition.derived : []).filter(isPlainObject).map((d) => d.id));
+    const levels = levelNamesOf(definition);
+    const formula = fields.find((n) => formulas.has(n) && !levels.has(n));
+    if (formula) return { ok: false, problem: `@${formula} is a formula: an amount reads stats as typed and levels` };
+  }
+  const num = (v) => { const n = Number(v); return Number.isFinite(n) ? n : 0; };
+  const value = evaluate(tree, {
+    field: (name) => num(sample[name]),
+    rule: (name) => ruleValue(name, sample),
+    table: (name, x) => lookupIn(isTable(name) ? tables[name] : [], x),
+  });
+  return { ok: true, value, reads: fields.map((id) => ({ id, label: names.get(id), value: num(sample[id]) })) };
+};
+
+/** Up to MOST formulas, `{ text, kind }` each, read against one sample: the box's request. */
+const previewFormulas = (definition, formulas) => {
+  const sample = sampleOf(definition);
+  return (Array.isArray(formulas) ? formulas : []).slice(0, MOST).map((f) => previewFormula(
+    definition, isPlainObject(f) ? f.text : undefined, isPlainObject(f) && KINDS.has(f.kind) ? f.kind : 'requires', sample,
+  ));
+};
+
+module.exports = { previewFormula, previewFormulas, SAMPLE_LEVEL, MOST, distance, nearest };
diff --git a/e2e/COVERAGE.md b/e2e/COVERAGE.md
index 08eec2cc..51f61e3a 100644
--- a/e2e/COVERAGE.md
+++ b/e2e/COVERAGE.md
@@ -87,6 +87,7 @@ panel), so a control that looks fine but does nothing is caught for all of them.
 | A bonus named on the field it changes | a stat as typed and with it; a formula with it | `choices_numbers` | `sheet-choices` (10 → 11, Guard Stance +1) | **AT THE TABLE** |
 | A rest refilling a feature's uses | the rest itself; one it counts as | `picking` | `sheet-choices` (a short rest) | **AT THE TABLE** (the rest itself) |
 | A list filled from a file | IMPORT: new and changed options and features, empty cells and `-`, skipped lines, same-named features | `choices_import` | `builder-choices-import` (this list downloaded, changed with one wrong line, uploaded, warned of, applied; played on a sheet) | **AT THE TABLE** |
+| Writing a formula | the formula box on REQUIRES, modifier amounts and USES: words and the sample's value, a mistake with its fix, SHAPE, INSERT | `formula_preview` | `builder-formula-box` | **BUILDER ONLY** (a builder aid: what it writes is played at the table by `sheet-choices` and `sheet-token-max`) |
 
 ## Sheets and NPCs
 
diff --git a/e2e/README.md b/e2e/README.md
index f367f914..63ed38ad 100644
--- a/e2e/README.md
+++ b/e2e/README.md
@@ -150,6 +150,7 @@ frontend suites.
 | `tests/parts-off.spec.ts` | Parts switched off at the table (coverage family 3): a custom system with every part on shows the player BANK and HIT_POINTS on the rail, MAX HEALTH, ARMOR and SAVE_STATS in their character controls and IMPORT on their sheet, and the GM INITIATIVE_TRACKER, PAY_PLAYERS, GIVE_ITEM and the buy-back rate; a version with bank, shops, initiative, combat, token health, sheet import and GIVE ITEM off hides every one; back on, they return |
 | `tests/sheet-nested-choices.spec.ts` | Lists inside lists, and a list everyone has (7a5a2): in the builder SPECIALTIES shows OPENED BY · SOLDIER: SPECIALTY (LV 3) and is set THROUGH FEATURES, COMMONS EVERYONE HAS IT, saved with no problems; published, a player's sheet has no SPECIALTIES block, COMMONS every character's with Improvement next at level 2 and then unlocked; SOLDIER at 3 offers PICK A SPECIALTY under its feature, DUELIST picked there with its own feature; lowered to 2 it waits, kept; back at 3 it counts again; as the server keeps it |
 | `tests/sheet-token-max.spec.ts` | A feature on the token's maximum (7a5a3): a player with a 20 HP token, a FIGHTER at level 3, picks TOUGH (+2 HP per level) and sees 26 / 26 on HIT_POINTS, the bonus named on the sheet's HP and MAX HEALTH at 26; a level down, 24; the GM opens their sheet from VIEW_PLAYER_INFO and drops TOUGH, and the token is back at 20 |
+| `tests/builder-formula-box.spec.ts` | The formula box (formula box 1): on Tough, `2 * @lvl` in red with USE @level, then +2 for each level · sample Level 3: +6 from the real server; PER CLASS LEVEL for FIGHTER at 3 and @con from INSERT at the cursor; AT LEAST on Fighter's REQUIRES (the sample meets it); the draft saved as written with no problems |
 | `tests/sheet-visibility.spec.ts` | Who sees what on a customized sheet (coverage family 1): its owner fills in a public field, a private one and a combat value and can't change the GM's field; another player, looking them up from GLOBAL_CHAT's user list (VIEW_PLAYER_INFO), sees only the public lines, and the server sends nothing else; the GM opens the whole sheet the same way (OPEN_SHEET) and sets the GM's field, which the owner then sees |
 | `tests/player-journey.spec.ts` | A custom system running (set up through the API), played in two browsers at once: a player makes a character and sees the system's words and its formula worked out; the GM types in a catalogue, gives the player something from it with a note, and calls a rest from the GAME tab; the player sees the gift arrive and the rest change their sheet |
 | `tests/builder-smoke.spec.ts` | The GM signs in, opens the System Builder, meets and skips the first-time tour (reset first, so it always shows), and goes back to the map |
diff --git a/e2e/tests/builder-clicks.spec.ts b/e2e/tests/builder-clicks.spec.ts
index 71d4a933..67aa0345 100644
--- a/e2e/tests/builder-clicks.spec.ts
+++ b/e2e/tests/builder-clicks.spec.ts
@@ -67,6 +67,9 @@ test('every control in the builder takes a click, on every page', async ({ page
       await feature.getByRole('button', { name: '+ MODIFIER' }).click();
       await feature.getByRole('combobox', { name: 'OPENS A LIST' }).selectOption({ label: 'NEW CHOICE' });
       await expect(feature.getByRole('spinbutton', { name: 'HOW MANY' })).toBeVisible();
+      // The modifier's formula box with its help open, so SHAPE and INSERT are there (formula box 1).
+      await feature.getByRole('button', { name: 'Help writing Modifier 1: by' }).click();
+      await expect(feature.getByRole('group', { name: 'Help writing Modifier 1: by' })).toBeVisible();
     }
     missed[p] = await unreachable(page);
     if (p === 'CHOICES') {
diff --git a/e2e/tests/builder-formula-box.spec.ts b/e2e/tests/builder-formula-box.spec.ts
new file mode 100644
index 00000000..4e524214
--- /dev/null
+++ b/e2e/tests/builder-formula-box.spec.ts
@@ -0,0 +1,72 @@
+import { test, expect } from '@playwright/test';
+import { signInAsGm, openBuilder, builderPage, gmToken, asGm } from './helpers';
+
+// The builder's formula box (formula box 1; approved mockup docs/mockups/formula-box.html,
+// 2026-10-29), read by the real server: a GM types a modifier with a misspelt name on Tough, sees it
+// in red with the fix, takes the fix and reads it in words with the sample's value; writes another
+// with a SHAPE and a name from INSERT; gives Fighter a requirement with AT LEAST; and finds the draft
+// saved as written.
+
+test('the formula box says a formula in words, catches a misspelt name, and writes one for you', async ({ page, request }, info) => {
+  const name = `Formula Hearth ${info.retry + 1}`;
+  const token = await gmToken(request);
+  const { id } = await asGm(request, token, 'post', '/api/systems', { definition: {
+    format: 1, name,
+    stats: [{ id: 'abilities', label: 'ABILITIES', stats: [{ id: 'str', label: 'Strength' }, { id: 'con', label: 'Constitution' }] }],
+    samples: { str: 16, con: 14 },
+    core: { health: { model: 'pool' } },
+    choices: [
+      { id: 'classes', one: 'Class', many: 'Classes', levelled: true, options: [{ id: 'fighter', label: 'Fighter', features: [] }] },
+      { id: 'feats', one: 'Feat', many: 'Feats', options: [{ id: 'tough', label: 'Tough', features: [{ id: 'tough_hp', label: 'Tough', modifiers: [{ target: 'str', amount: '1' }] }] }] },
+    ],
+  } });
+  await signInAsGm(page);
+  await openBuilder(page);
+  const card = page.getByTestId(/^system-/).filter({ hasText: name.toUpperCase() });
+  if (!(await card.getByRole('button', { name: 'OPEN', exact: true }).isVisible())) await card.getByRole('button').first().click();
+  await card.getByRole('button', { name: 'OPEN', exact: true }).click();
+  await builderPage(page, 'CHOICES');
+
+  // Tough: a misspelt name, said in red with the nearest real one; USE @level fixes it.
+  await page.getByRole('button', { name: /^FEATS/ }).click();
+  const tough = page.getByRole('region', { name: 'Tough option' });
+  await tough.getByRole('button', { name: /^▸ TOUGH/ }).click();
+  const feature = tough.getByRole('group', { name: 'Feature Tough' });
+  const amount = feature.getByRole('textbox', { name: 'Modifier 1: by' });
+  await amount.fill('2 * @lvl');
+  const words = feature.getByTestId('formula-words');
+  await expect(words).toContainText("@lvl isn't one of this system's names");
+  await expect(amount).toHaveAttribute('aria-invalid', 'true');
+  await feature.getByRole('button', { name: 'USE @level' }).click();
+  await expect(amount).toHaveValue('2 * @level');
+  await expect(words).toHaveText('+2 for each level · sample Level 3: +6');
+
+  // A SHAPE writes one, and a name from INSERT goes in at the cursor.
+  await feature.getByRole('button', { name: 'Help writing Modifier 1: by' }).click();
+  const help = feature.getByRole('group', { name: 'Help writing Modifier 1: by' });
+  await help.getByRole('button', { name: 'PER CLASS LEVEL' }).click();
+  await help.getByRole('combobox', { name: 'Which level' }).selectOption({ label: 'FIGHTER' });
+  await help.getByRole('spinbutton', { name: 'How many' }).fill('3');
+  await expect(amount).toHaveValue('3 * @fighter_level');
+  await expect(words).toHaveText('+3 for each fighter level · sample Fighter level 3: +9');
+  await amount.press('End');
+  await amount.pressSequentially(' + ');
+  await help.getByRole('button', { name: /^@con / }).click();
+  await expect(amount).toHaveValue('3 * @fighter_level + @con');
+  await expect(words).toHaveText('worked out from Fighter level, Constitution · sample Fighter level 3, Constitution 14: +23');
+
+  // Fighter needs STR 13, written by AT LEAST; the sample has 16.
+  await page.getByRole('button', { name: /^CLASSES/ }).click();
+  const fighter = page.getByRole('region', { name: 'Fighter option' });
+  await fighter.getByRole('button', { name: 'Help writing REQUIRES' }).click();
+  await fighter.getByRole('group', { name: 'Help writing REQUIRES' }).getByRole('button', { name: 'AT LEAST', exact: true }).click();
+  await expect(fighter.getByRole('textbox', { name: 'REQUIRES' })).toHaveValue('@str >= 13');
+  await expect(fighter.getByTestId('formula-words')).toHaveText('needs Strength 13 or more · the sample (Strength 16) meets it');
+
+  // Saved as written, with no problems.
+  await expect.poll(async () => {
+    const { draft } = await asGm(request, token, 'get', `/api/systems/${id}`);
+    return [draft.choices[1].options[0].features[0].modifiers[0].amount, draft.choices[0].options[0].requires];
+  }).toEqual(['3 * @fighter_level + @con', '@str >= 13']);
+  expect((await asGm(request, token, 'get', `/api/systems/${id}`)).problems).toEqual([]);
+});
diff --git a/frontend/src/components/ChoicesPage.tsx b/frontend/src/components/ChoicesPage.tsx
index b2217bbe..107a6773 100644
--- a/frontend/src/components/ChoicesPage.tsx
+++ b/frontend/src/components/ChoicesPage.tsx
@@ -9,6 +9,7 @@ import { FieldName } from './HelpHint';
 import { FeaturesEditor } from './FeaturesEditor';
 import { ChoicesImport } from './ChoicesImport';
 import { ToggleSwitch } from './ToggleSwitch';
+import { useFormulaBox } from '../hooks/useFormulaBox';
 
 // The builder's CHOICES page (7a2b1; approved mockup docs/mockups/builder-choices.html, 2026-10-27):
 // the lists a character picks from (classes, backgrounds, feats), named in the game's own words. The
@@ -21,7 +22,7 @@ import { ToggleSwitch } from './ToggleSwitch';
 interface Props {
   definition: Definition;
   edit: (next: Definition) => void;
-  /** The server, for IMPORT's PREVIEW; none when looking at an example. */
+  /** The server, for IMPORT's PREVIEW and the formula boxes; none when looking at an example. */
   api?: ReturnType<typeof systemsApi>;
 }
 
@@ -158,10 +159,14 @@ function ListPanel({ list, definition, edit, picked, onPick, onImport, fresh, st
   );
 }
 
-function OptionPanel({ list, option, definition, edit }: Props & { list: ChoiceList; option: ChoiceOption }) {
+function OptionPanel({ list, option, definition, edit, api }: Props & { list: ChoiceList; option: ChoiceOption }) {
   const set = (patch: Parameters<typeof withOption>[3]) => edit(withOption(definition, list.id, option.id, patch));
   const features = (option.features ?? []).filter((f): f is { id: string; label?: string } => !!f && typeof f === 'object' && typeof (f as { id?: unknown }).id === 'string');
   const id = (part: string) => `choice-${list.id}-${option.id}-${part}`;
+  const requires = useFormulaBox({
+    definition, api, kind: 'requires', value: option.requires ?? '', onChange: (text) => set({ requires: text }),
+    label: 'REQUIRES', id: id('requires'), placeholder: 'NOTHING · @int >= 13', inputStyle: input,
+  });
   return (
     <section aria-label={`${option.label || option.id} option`} style={panel}>
       <div style={{ ...row, justifyContent: 'space-between' }}>
@@ -177,11 +182,10 @@ function OptionPanel({ list, option, definition, edit }: Props & { list: ChoiceL
         <textarea id={id('description')} rows={2} maxLength={LIMITS.description} value={option.description ?? ''}
           style={{ ...input, resize: 'vertical', fontFamily: 'inherit' }} onChange={(e) => set({ description: e.target.value })} />
         <FieldName boxStyle={END} htmlFor={id('requires')} hint={HINTS['choices.requires']} style={small}>REQUIRES</FieldName>
-        <input id={id('requires')} type="text" maxLength={1000} value={option.requires ?? ''} placeholder="NOTHING · @int >= 13" style={input}
-          onChange={(e) => set({ requires: e.target.value })} />
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 4, minWidth: 0 }}>{requires.field}{requires.help}</div>
       </div>
       {list.levelled && <p style={{ ...why, fontSize: 11, opacity: 0.7 }}>Its level reads as {levelNames(list).options[option.id]} in formulas: 0 for a character without it.</p>}
-      <FeaturesEditor definition={definition} edit={edit} list={list} option={option} />
+      <FeaturesEditor definition={definition} edit={edit} list={list} option={option} api={api} />
     </section>
   );
 }
@@ -240,7 +244,7 @@ export function ChoicesPage({ definition, edit, api }: Props) {
           onImport={() => { setImporting(list.id); setApplied(null); }}
           fresh={applied?.list === list.id ? applied.added : NONE} status={applied?.list === list.id ? applied.text : null} />
       )}
-      {list && option && importing !== list.id && <OptionPanel key={`${list.id}:${option.id}`} list={list} option={option} definition={definition} edit={edit} />}
+      {list && option && importing !== list.id && <OptionPanel key={`${list.id}:${option.id}`} list={list} option={option} definition={definition} edit={edit} api={api} />}
     </div>
   );
 }
diff --git a/frontend/src/components/FeaturesEditor.tsx b/frontend/src/components/FeaturesEditor.tsx
index 37c9fb32..14724e12 100644
--- a/frontend/src/components/FeaturesEditor.tsx
+++ b/frontend/src/components/FeaturesEditor.tsx
@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import type { Definition } from '../sheets/systemsApi';
+import type { Definition, systemsApi } from '../sheets/systemsApi';
 import {
   featureList, levelOf, kindsOf, withNewFeature, withFeature, withoutFeature, modifierTargets, refillRests, rollChoices, choiceLists, pickedOf, unlocksByLevel, LIMITS,
   type ChoiceList, type ChoiceOption, type Feature, type FeatureKind, type FeaturePatch,
@@ -7,6 +7,7 @@ import {
 import { HINTS } from '../sheets/builderHelp';
 import { FieldName } from './HelpHint';
 import { ToggleSwitch } from './ToggleSwitch';
+import { useFormulaBox } from '../hooks/useFormulaBox';
 
 // An option's features on the CHOICES page (7a2b2; approved mockup docs/mockups/builder-choices.html,
 // 2026-10-27): what a pick gives, grouped by the level each unlocks at in a levelled list. Each row
@@ -20,6 +21,8 @@ interface Props {
   edit: (next: Definition) => void;
   list: ChoiceList;
   option: ChoiceOption;
+  /** The server, for the formula boxes' words and sample values; none when looking at an example. */
+  api?: ReturnType<typeof systemsApi>;
 }
 
 const small: React.CSSProperties = { fontSize: 10, letterSpacing: 2, opacity: 0.75 };
@@ -45,7 +48,33 @@ const Tag = ({ kind }: { kind: FeatureKind }) => (
   <span style={{ fontSize: 9, letterSpacing: 1, border: '1px solid currentColor', padding: '0 4px', color: TAGS[kind][1], whiteSpace: 'nowrap' }}>{TAGS[kind][0]}</span>
 );
 
-function FeatureForm({ definition, edit, list, option, feature }: Props & { feature: Feature }) {
+type Modifier = NonNullable<Feature['modifiers']>[number];
+
+/** One modifier: what it changes, by how much (a formula box), and × in red; the box's words and help under the row. */
+function ModifierRow({ definition, api, i, m, targets, onChange, onRemove }: {
+  definition: Definition; api?: Props['api']; i: number; m: Modifier; targets: ReturnType<typeof modifierTargets>;
+  onChange: (next: Modifier) => void; onRemove: () => void;
+}) {
+  const amount = useFormulaBox({
+    definition, api, kind: 'amount', value: m.amount, onChange: (text) => onChange({ ...m, amount: text }),
+    label: `Modifier ${i + 1}: by`, placeholder: '1 · @mage_level', inputStyle: input,
+  });
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+      <span style={{ display: 'grid', gridTemplateColumns: 'minmax(0, 2fr) minmax(0, 3fr) auto', gap: 6, alignItems: 'center' }}>
+        <select aria-label={`Modifier ${i + 1}: changes`} value={m.target} style={input} onChange={(e) => onChange({ ...m, target: e.target.value })}>
+          {!targets.some((g) => g.items.some((t) => t.id === m.target)) && <option value={m.target}>{m.target || 'PICK ONE'}</option>}
+          {targets.map((g) => <optgroup key={g.group} label={g.group}>{g.items.map((t) => <option key={t.id} value={t.id}>{t.label}</option>)}</optgroup>)}
+        </select>
+        {amount.field}
+        <button type="button" className="utility-btn" style={{ ...xBtn, color: 'var(--danger)', borderColor: 'var(--danger)' }} aria-label={`Remove modifier ${i + 1}`} onClick={onRemove}>×</button>
+      </span>
+      {amount.help}
+    </div>
+  );
+}
+
+function FeatureForm({ definition, edit, list, option, feature, api }: Props & { feature: Feature }) {
   const [asking, setAsking] = useState(false);
   const set = (patch: FeaturePatch) => edit(withFeature(definition, list.id, option.id, feature.id, patch));
   // The level is set when the box is left (or on Enter), not as it is typed: a new level moves the
@@ -67,6 +96,11 @@ function FeatureForm({ definition, edit, list, option, feature }: Props & { feat
   const given = new Set(feature.rolls ?? []);
   const id = (part: string) => `feature-${feature.id}-${part}`;
   const name = feature.label.trim() || 'this feature';
+  // Made whether or not it has uses (a hook can't wait behind HAS USES); shown only when it does.
+  const usesBox = useFormulaBox({
+    definition, api, kind: 'uses', value: feature.uses?.count ?? '', onChange: (text) => { if (feature.uses) set({ uses: { ...feature.uses, count: text } }); },
+    label: 'How many uses', placeholder: '1 · @level', inputStyle: input,
+  });
   return (
     <div role="group" aria-label={`Feature ${feature.label || feature.id}`} style={{ display: 'flex', flexDirection: 'column', gap: 10, padding: '10px 12px', border: '1px solid var(--green)', background: 'color-mix(in srgb, var(--green) 4%, transparent)' }}>
       <div style={grid}>
@@ -85,17 +119,9 @@ function FeatureForm({ definition, edit, list, option, feature }: Props & { feat
         <FieldName boxStyle={END} hint={HINTS['choices.modifiers']} style={small}>MODIFIERS</FieldName>
         <div role="group" aria-label="Modifiers" style={{ display: 'flex', flexDirection: 'column', gap: 5 }}>
           {mods.map((m, i) => (
-            <span key={i} style={{ display: 'grid', gridTemplateColumns: 'minmax(0, 1fr) minmax(0, 1fr) auto', gap: 6, alignItems: 'center' }}>
-              <select aria-label={`Modifier ${i + 1}: changes`} value={m.target} style={input}
-                onChange={(e) => set({ modifiers: mods.map((x, j) => (j === i ? { ...x, target: e.target.value } : x)) })}>
-                {!targets.some((g) => g.items.some((t) => t.id === m.target)) && <option value={m.target}>{m.target || 'PICK ONE'}</option>}
-                {targets.map((g) => <optgroup key={g.group} label={g.group}>{g.items.map((t) => <option key={t.id} value={t.id}>{t.label}</option>)}</optgroup>)}
-              </select>
-              <input type="text" aria-label={`Modifier ${i + 1}: by`} maxLength={1000} value={m.amount} placeholder="1 · @mage_level" style={input}
-                onChange={(e) => set({ modifiers: mods.map((x, j) => (j === i ? { ...x, amount: e.target.value } : x)) })} />
-              <button type="button" className="utility-btn" style={xBtn} aria-label={`Remove modifier ${i + 1}`}
-                onClick={() => set({ modifiers: mods.filter((_, j) => j !== i) })}>×</button>
-            </span>
+            <ModifierRow key={i} definition={definition} api={api} i={i} m={m} targets={targets}
+              onChange={(next) => set({ modifiers: mods.map((x, j) => (j === i ? next : x)) })}
+              onRemove={() => set({ modifiers: mods.filter((_, j) => j !== i) })} />
           ))}
           <div><button type="button" className="utility-btn" style={btn} disabled={mods.length >= LIMITS.modifiers || !targets.length}
             onClick={() => set({ modifiers: [...mods, { target: targets[0].items[0].id, amount: '1' }] })}>+ MODIFIER</button></div>
@@ -108,8 +134,7 @@ function FeatureForm({ definition, edit, list, option, feature }: Props & { feat
             onChange={(has) => set({ uses: has ? { count: '1', refill: rests[0]?.id } : null })} />
           {feature.uses && (
             <span style={row}>
-              <input type="text" aria-label="How many uses" maxLength={1000} value={feature.uses.count} placeholder="1 · @level" style={{ ...input, width: 120 }}
-                onChange={(e) => set({ uses: { ...feature.uses!, count: e.target.value } })} />
+              <span style={{ width: 170 }}>{usesBox.field}</span>
               <span style={small}>REFILLED BY</span>
               <select aria-label="Refilled by" value={feature.uses.refill ?? ''} style={input}
                 onChange={(e) => set({ uses: { count: feature.uses!.count, refill: e.target.value } })}>
@@ -118,6 +143,7 @@ function FeatureForm({ definition, edit, list, option, feature }: Props & { feat
               </select>
             </span>
           )}
+          {feature.uses && usesBox.help}
         </div>
 
         <FieldName boxStyle={END} hint={HINTS['choices.rolls']} style={small}>GIVES ROLLS</FieldName>
@@ -188,7 +214,7 @@ function FeatureForm({ definition, edit, list, option, feature }: Props & { feat
   );
 }
 
-export function FeaturesEditor({ definition, edit, list, option }: Props) {
+export function FeaturesEditor({ definition, edit, list, option, api }: Props) {
   const features = featureList(option);
   const [open, setOpen] = useState<string | null>(null);
   // In a levelled list (or one everyone has), by the level each unlocks at; otherwise all together.
@@ -217,7 +243,7 @@ export function FeaturesEditor({ definition, edit, list, option }: Props) {
                 <span>{open === f.id ? '▾' : '▸'} {(f.label.trim() || 'NEEDS A NAME').toUpperCase()}</span>
                 {kindsOf(f).map((k) => <Tag key={k} kind={k} />)}
               </button>
-              {open === f.id && <FeatureForm key={`form:${f.id}`} definition={definition} edit={edit} list={list} option={option} feature={f} />}
+              {open === f.id && <FeatureForm key={`form:${f.id}`} definition={definition} edit={edit} list={list} option={option} feature={f} api={api} />}
             </React.Fragment>
           ))}
         </section>
diff --git a/frontend/src/components/FormulaIcon.tsx b/frontend/src/components/FormulaIcon.tsx
new file mode 100644
index 00000000..a62294eb
--- /dev/null
+++ b/frontend/src/components/FormulaIcon.tsx
@@ -0,0 +1,13 @@
+import React from 'react';
+
+/**
+ * The FORMULA button's mark: "math format professional" from Microsoft's Fluent UI System Icons
+ * (MIT), picked by the user 2026-10-29; drawn in the text's color so it follows the theme.
+ */
+export function FormulaIcon({ size = 16 }: { size?: number }) {
+  return (
+    <svg aria-hidden width={size} height={size} viewBox="0 0 20 20">
+      <path fill="currentColor" d="M10.25 3.6c.442-.332 1.005-.65 1.65-.65a1 1 0 0 1 .123.01c.427.072.767.23 1.062.503c.24.224.435.516.611.78l1.075-1.073a.75.75 0 1 1 1.06 1.06l-1.336 1.337a26 26 0 0 1 .375.698c.083.165.179.245.382.3a.7.7 0 0 0 .157.01a.1.1 0 0 0 .03-.008a.5.5 0 0 0 .096-.072c.06-.053.129-.12.234-.225a.75.75 0 0 1 1.06 1.06l-.033.034c-.17.17-.4.4-.686.545c-.36.18-.733.198-1.134.131l-.059-.012c-.576-.144-1.075-.466-1.389-1.092l-.139-.264l-1.058 1.059a.75.75 0 1 1-1.06-1.061l1.346-1.346a3 3 0 0 0-.142-.208c-.216-.325-.315-.464-.411-.554a.4.4 0 0 0-.22-.109c-.154.018-.377.11-.695.347a.75.75 0 0 1-.9-1.2M5.4 16.3H6c1.4-.1 2.8-.7 3.9-2c.3-.4.2-.8-.1-1.1c-.3-.2-.8-.2-1.2.1c-.9.7-1.9 1.4-3.1 1.4c-.6 0-1.2-.5-1.3-1.1c-.1-.5 0-1.1.2-1.6c1.6.1 3.8-.1 4.8-1.3c.8-.9 1-2.4 0-3.3c-.4-.4-.9-.5-1.4-.5c-.9 0-1.8.5-2.6 1.3c-1.3 1.3-2.6 3.5-2.4 5.6c.1 1.5 1.4 2.4 2.6 2.5m.8-7.1c.6-.5 1.1-.8 1.6-.8c.2 0 .5.1.6.3c.2.3 0 .8-.2 1c-.5.5-1.8.8-3 .8c.3-.5.6-.9 1-1.3" />
+    </svg>
+  );
+}
diff --git a/frontend/src/hooks/__tests__/useFormulaBox.test.tsx b/frontend/src/hooks/__tests__/useFormulaBox.test.tsx
new file mode 100644
index 00000000..6891a323
--- /dev/null
+++ b/frontend/src/hooks/__tests__/useFormulaBox.test.tsx
@@ -0,0 +1,118 @@
+import React, { useState } from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useFormulaBox } from '../useFormulaBox';
+import type { Definition, systemsApi } from '../../sheets/systemsApi';
+import type { FormulaKind, FormulaRead } from '../../sheets/formulaBox';
+
+/**
+ * The formula box (formula box 1; approved mockup docs/mockups/formula-box.html, 2026-10-29): the
+ * words line under it with the server's sample value, a mistake in red with USE @name, an answer
+ * for older text never shown; the FORMULA button alone opening SHAPE and INSERT; a shape writing
+ * the formula; INSERT putting a name at the cursor.
+ */
+const DEF = {
+  format: 1, name: 'Hearth',
+  stats: [{ id: 'abilities', label: 'ABILITIES', stats: [{ id: 'str', label: 'Strength' }] }],
+  choices: [{ id: 'classes', one: 'Class', many: 'Classes', levelled: true, options: [{ id: 'fighter', label: 'Fighter', features: [] }] }],
+} as unknown as Definition;
+
+const apiAnswering = (answer: (text: string) => FormulaRead) => ({
+  previewFormulas: vi.fn(async (_d: Definition, formulas: { text: string }[]) => ({ ok: true, value: { results: formulas.map((f) => answer(f.text)), sampleLevel: 3 } })),
+}) as unknown as ReturnType<typeof systemsApi> & { previewFormulas: ReturnType<typeof vi.fn> };
+
+function Harness({ kind = 'amount', start = '', api }: { kind?: FormulaKind; start?: string; api?: ReturnType<typeof systemsApi> }) {
+  const [text, setText] = useState(start);
+  const box = useFormulaBox({ definition: DEF, api, kind, value: text, onChange: setText, label: 'Modifier 1: by', inputStyle: {} });
+  return <div>{box.field}{box.help}</div>;
+}
+const textbox = () => screen.getByRole('textbox', { name: 'Modifier 1: by' }) as HTMLInputElement;
+const words = () => screen.getByTestId('formula-words');
+
+describe('the formula box', () => {
+  it('says it in words, then what the server makes of it for the sample', async () => {
+    const api = apiAnswering(() => ({ ok: true, value: 6, reads: [{ id: 'level', label: 'Level', value: 3 }] }));
+    render(<Harness start="2 * @level" api={api} />);
+    expect(words().textContent).toBe('+2 for each level');
+    await waitFor(() => expect(words().textContent).toBe('+2 for each level · sample Level 3: +6'));
+    expect(api.previewFormulas).toHaveBeenCalledWith(DEF, [{ text: '2 * @level', kind: 'amount' }]);
+  });
+
+  it('says nothing under an empty box, and asks the server nothing', async () => {
+    const api = apiAnswering(() => ({ ok: true, value: 0, reads: [] }));
+    render(<Harness api={api} />);
+    expect(screen.queryByTestId('formula-words')).toBeNull();
+    await new Promise((r) => setTimeout(r, 450));
+    expect(api.previewFormulas).not.toHaveBeenCalled();
+  });
+
+  it('shows a mistake in red, the box marked, and USE @name fixes it', async () => {
+    const api = apiAnswering((text) => (text.includes('@lvl')
+      ? { ok: false, problem: "@lvl isn't one of this system's names", name: 'lvl', suggest: 'level' }
+      : { ok: true, value: 6, reads: [{ id: 'level', label: 'Level', value: 3 }] }));
+    render(<Harness start="2 * @lvl" api={api} />);
+    await waitFor(() => expect(words().textContent).toContain("@lvl isn't one of this system's names"));
+    expect(textbox().getAttribute('aria-invalid')).toBe('true');
+    await userEvent.click(screen.getByRole('button', { name: 'USE @level' }));
+    expect(textbox().value).toBe('2 * @level');
+    await waitFor(() => expect(words().textContent).toBe('+2 for each level · sample Level 3: +6'));
+    expect(textbox().hasAttribute('aria-invalid')).toBe(false);
+  });
+
+  it('never shows an answer for text that has since changed', async () => {
+    const api = apiAnswering(() => ({ ok: true, value: 99, reads: [] }));
+    render(<Harness start="99" api={api} />);
+    await waitFor(() => expect(words().textContent).toBe('+99, always · +99'));
+    fireEvent.change(textbox(), { target: { value: '5' } });
+    expect(words().textContent).toBe('+5, always');
+  });
+
+  it('opens SHAPE and INSERT only by the FORMULA button, which says it is open', async () => {
+    render(<Harness />);
+    const button = screen.getByRole('button', { name: 'Help writing Modifier 1: by' });
+    await userEvent.click(textbox());
+    expect(screen.queryByRole('group', { name: 'Help writing Modifier 1: by' })).toBeNull();
+    await userEvent.click(button);
+    expect(button.getAttribute('aria-expanded')).toBe('true');
+    const help = screen.getByRole('group', { name: 'Help writing Modifier 1: by' });
+    expect(within(help).getByText('SHAPE')).toBeTruthy();
+    expect(within(help).getByText('LEVELS')).toBeTruthy();
+    await userEvent.click(button);
+    expect(screen.queryByRole('group', { name: 'Help writing Modifier 1: by' })).toBeNull();
+  });
+
+  it('writes a shape, and rewrites it as its number changes', async () => {
+    render(<Harness />);
+    await userEvent.click(screen.getByRole('button', { name: 'Help writing Modifier 1: by' }));
+    await userEvent.click(screen.getByRole('button', { name: 'PER LEVEL' }));
+    expect(textbox().value).toBe('2 * @level');
+    fireEvent.change(screen.getByRole('spinbutton', { name: 'How many' }), { target: { value: '3' } });
+    expect(textbox().value).toBe('3 * @level');
+    await userEvent.click(screen.getByRole('button', { name: 'PER CLASS LEVEL' }));
+    expect(textbox().value).toBe('2 * @classes_level');
+    fireEvent.change(screen.getByRole('combobox', { name: 'Which level' }), { target: { value: '@fighter_level' } });
+    expect(textbox().value).toBe('2 * @fighter_level');
+    await userEvent.click(screen.getByRole('button', { name: 'HALF LEVEL' }));
+    expect(textbox().value).toBe('floor(@level / 2)');
+    expect(screen.queryByRole('spinbutton', { name: 'How many' })).toBeNull();
+  });
+
+  it('writes a requirement on a stat', async () => {
+    render(<Harness kind="requires" />);
+    await userEvent.click(screen.getByRole('button', { name: 'Help writing Modifier 1: by' }));
+    await userEvent.click(screen.getByRole('button', { name: 'AT LEAST' }));
+    expect(textbox().value).toBe('@str >= 13');
+    expect(screen.queryByRole('button', { name: 'PER LEVEL' })).toBeNull();
+  });
+
+  it('puts an INSERT name at the cursor', async () => {
+    render(<Harness start="2 *  + 1" />);
+    textbox().setSelectionRange(4, 4);
+    fireEvent.select(textbox());
+    await userEvent.click(screen.getByRole('button', { name: 'Help writing Modifier 1: by' }));
+    await userEvent.click(screen.getByRole('button', { name: /^@fighter_level/ }));
+    expect(textbox().value).toBe('2 * @fighter_level + 1');
+    expect(textbox().selectionStart).toBe(18);
+  });
+});
diff --git a/frontend/src/hooks/useFormulaBox.tsx b/frontend/src/hooks/useFormulaBox.tsx
new file mode 100644
index 00000000..1d2583fd
--- /dev/null
+++ b/frontend/src/hooks/useFormulaBox.tsx
@@ -0,0 +1,170 @@
+import React, { useEffect, useRef, useState } from 'react';
+import type { Definition, systemsApi } from '../sheets/systemsApi';
+import {
+  wordsOf, sampleLine, insertGroups, shapesOf, writeShape, levelTokens,
+  type FormulaKind, type FormulaRead, type Shape,
+} from '../sheets/formulaBox';
+import { allStats, insertToken } from '../sheets/statsRules';
+import { FormulaIcon } from '../components/FormulaIcon';
+import { PREVIEW_DELAY_MS } from './usePreviewValues';
+
+// The builder's formula box (formula box 1; approved mockup docs/mockups/formula-box.html,
+// 2026-10-29): a formula's text with a FORMULA button beside it. Under it, always, one line saying
+// it in words with what it comes to for the sample character, or its mistake in red with a fix for
+// a name nearly right. The button opens SHAPE (a common formula written for you) and INSERT (the
+// names it can read, put at the cursor); only the button opens them, so typing is never covered.
+// The words, shapes and names are sheets/formulaBox.ts; the server reads the formula. The
+// button's mark is components/FormulaIcon.tsx.
+
+interface Options {
+  definition: Definition;
+  api?: ReturnType<typeof systemsApi>;
+  kind: FormulaKind;
+  value: string;
+  onChange: (text: string) => void;
+  /** The box's name: `Modifier 1: by`. */
+  label: string;
+  /** The text box's id, for a label beside it. */
+  id?: string;
+  placeholder?: string;
+  inputStyle: React.CSSProperties;
+}
+
+const small: React.CSSProperties = { fontSize: 9, letterSpacing: 3, opacity: 0.7 };
+const chip = (on: boolean): React.CSSProperties => ({
+  border: `1px ${on ? 'solid' : 'dashed'} var(--green)`, background: on ? 'color-mix(in srgb, var(--green) 20%, transparent)' : 'none',
+  color: 'var(--green)', fontFamily: 'monospace', fontSize: 10, letterSpacing: 1, padding: '3px 7px', cursor: 'pointer',
+});
+const askBox: React.CSSProperties = { background: 'var(--black)', color: 'var(--cyan)', border: '1px solid var(--cyan)', fontFamily: 'monospace', fontSize: 11, padding: '2px 5px' };
+
+/** What a shape starts at: 1 to add, 13 for a stat, 5 for a level. */
+const startOf = (s: Shape) => (s.id === 'at_least' ? 13 : s.id === 'level_at_least' ? 5 : s.id === 'per_level' || s.id === 'per_class_level' ? 2 : 1);
+
+/**
+ * The box, as two parts the caller places: `field`, the text and its FORMULA button, where the
+ * text box was; and `help`, the words line and (while open) SHAPE and INSERT, under the row.
+ */
+export function useFormulaBox({ definition, api, kind, value, onChange, label, id, placeholder, inputStyle }: Options): { field: React.ReactElement; help: React.ReactElement } {
+  const [open, setOpen] = useState(false);
+  // What the server said, kept with the text it was said of: an answer for older text is never shown.
+  const [read, setRead] = useState<{ text: string; result: FormulaRead } | null>(null);
+  const [shape, setShape] = useState<{ id: string; n: number; name: string } | null>(null);
+  const input = useRef<HTMLInputElement | null>(null);
+  const cursor = useRef(value.length);
+  const placeAt = useRef<number | null>(null);
+
+  // The server reads it a moment after typing stops, as STATS & RULES' live values are.
+  useEffect(() => {
+    if (!api || !value.trim()) return undefined;
+    let live = true;
+    const timer = setTimeout(() => {
+      api.previewFormulas(definition, [{ text: value, kind }]).then((r) => { if (live && r.ok && r.value.results[0]) setRead({ text: value, result: r.value.results[0] }); });
+    }, PREVIEW_DELAY_MS);
+    return () => { live = false; clearTimeout(timer); };
+  }, [api, definition, value, kind]);
+
+  // After INSERT, the cursor goes after what was put in.
+  useEffect(() => {
+    if (placeAt.current === null || !input.current) return;
+    input.current.focus();
+    input.current.setSelectionRange(placeAt.current, placeAt.current);
+    cursor.current = placeAt.current;
+    placeAt.current = null;
+  });
+
+  const shapes = shapesOf(definition, kind);
+  const levels = levelTokens(definition);
+  const stats = allStats(definition).map((s) => ({ token: `@${s.id}`, label: (s.label || s.id).toUpperCase() }));
+  const write = (s: { id: string; n: number; name: string }) => { setShape(s); onChange(writeShape(s.id, s.n, s.name)); };
+  const pick = (s: Shape) => {
+    const names = s.asks === 'number-and-stat' ? stats : s.asks === 'number-and-level' ? levels.filter((l) => s.id !== 'per_class_level' || l.token !== '@level') : [];
+    write({ id: s.id, n: startOf(s), name: names[0]?.token ?? '@level' });
+  };
+  const current = shapes.find((s) => s.id === shape?.id);
+  const shown = value.trim() && read?.text === value ? read.result : null;
+  const bad = !!shown && !shown.ok;
+
+  const field = (
+    <span style={{ display: 'flex', gap: 6, minWidth: 0 }}>
+      <input ref={input} id={id} type="text" aria-label={label} maxLength={1000} value={value} placeholder={placeholder} spellCheck={false}
+        aria-invalid={bad ? true : undefined}
+        style={{ ...inputStyle, flex: 1, minWidth: 0, ...(bad ? { borderColor: 'var(--danger)' } : {}) }}
+        onChange={(e) => { setShape(null); onChange(e.target.value); cursor.current = e.target.selectionStart ?? e.target.value.length; }}
+        onSelect={(e) => { cursor.current = (e.target as HTMLInputElement).selectionStart ?? 0; }} />
+      <button type="button" aria-label={`Help writing ${label}`} aria-expanded={open} title="Help writing it" onClick={() => setOpen(!open)}
+        style={{
+          width: 28, flexShrink: 0, padding: 0, display: 'flex', alignItems: 'center', justifyContent: 'center', cursor: 'pointer',
+          border: `1px ${open ? 'solid var(--cyan)' : 'dashed var(--green)'}`, color: open ? 'var(--cyan)' : 'var(--green)',
+          background: open ? 'color-mix(in srgb, var(--cyan) 18%, transparent)' : 'none',
+        }}>
+        <FormulaIcon />
+      </button>
+    </span>
+  );
+
+  const words = wordsOf(kind, value, shown && shown.ok ? shown.reads : []);
+  const help = (
+    <>
+      {value.trim() && (
+        <div role="status" data-testid="formula-words" style={{ textAlign: 'left', fontSize: 11, lineHeight: 1.5, color: bad ? 'var(--danger)' : 'var(--cyan)', display: 'flex', gap: 6, flexWrap: 'wrap', alignItems: 'center' }}>
+          {bad && shown && !shown.ok
+            ? <>
+                <span>{shown.problem}</span>
+                {shown.name && shown.suggest && (
+                  <button type="button" style={chip(false)}
+                    onClick={() => onChange(value.replace(new RegExp(`@${shown.name}(?![a-z0-9_])`), `@${shown.suggest}`))}>USE @{shown.suggest}</button>
+                )}
+              </>
+            : <span>{words}{shown && shown.ok && <span style={{ color: 'var(--green)', opacity: 0.75 }}> · {sampleLine(kind, shown)}</span>}</span>}
+        </div>
+      )}
+      {open && (
+        <div role="group" aria-label={`Help writing ${label}`} style={{ textAlign: 'left', border: '1px solid var(--cyan)', padding: '8px 10px', display: 'flex', flexDirection: 'column', gap: 6, fontSize: 11 }}>
+          <div style={{ display: 'flex', gap: 5, flexWrap: 'wrap', alignItems: 'center' }}>
+            <span style={small}>SHAPE</span>
+            {shapes.map((s) => (
+              <button key={s.id} type="button" disabled={!!s.needs} title={s.needs} aria-pressed={shape?.id === s.id}
+                style={{ ...chip(shape?.id === s.id), opacity: s.needs ? 0.45 : 1, cursor: s.needs ? 'default' : 'pointer' }} onClick={() => pick(s)}>{s.label}</button>
+            ))}
+          </div>
+          {shape && current && current.asks !== 'none' && (
+            <div style={{ display: 'flex', gap: 5, flexWrap: 'wrap', alignItems: 'center', color: 'var(--cyan)' }}>
+              {kind === 'requires' ? 'NEEDS' : kind === 'amount' ? 'ADD' : ''}
+              {kind === 'requires' && (
+                <select aria-label="Which" value={shape.name} style={askBox} onChange={(e) => write({ ...shape, name: e.target.value })}>
+                  {(current.asks === 'number-and-stat' ? stats : levels).map((o) => <option key={o.token} value={o.token}>{o.label}</option>)}
+                </select>
+              )}
+              {kind === 'requires' && 'OF AT LEAST'}
+              <input type="number" aria-label="How many" value={shape.n} style={{ ...askBox, width: 56 }} onChange={(e) => write({ ...shape, n: Number(e.target.value) })} />
+              {kind === 'uses' && shape.id === 'number' && 'USES'}
+              {shape.id === 'per_level' && 'FOR EACH LEVEL'}
+              {shape.id === 'per_class_level' && <>
+                FOR EACH
+                <select aria-label="Which level" value={shape.name} style={askBox} onChange={(e) => write({ ...shape, name: e.target.value })}>
+                  {levels.filter((l) => l.token !== '@level').map((o) => <option key={o.token} value={o.token}>{o.label.replace(/ LEVEL$/, '')}</option>)}
+                </select>
+                LEVEL
+              </>}
+            </div>
+          )}
+          {insertGroups(definition, kind).map((g) => (
+            <div key={g.title} style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+              <span style={small}>{g.title}</span>
+              <div style={{ display: 'flex', gap: '2px 10px', flexWrap: 'wrap' }}>
+                {g.items.map((it) => (
+                  <button key={it.token} type="button" onMouseDown={(e) => e.preventDefault()}
+                    onClick={() => { const next = insertToken(value, cursor.current, it.token); placeAt.current = next.cursor; setShape(null); onChange(next.text); }}
+                    style={{ background: 'none', border: 0, padding: 0, color: 'var(--cyan)', fontFamily: 'monospace', fontSize: 11, cursor: 'pointer' }}>
+                    {it.token} <span style={{ fontSize: 9, opacity: 0.6 }}>{it.label}</span>
+                  </button>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </>
+  );
+  return { field, help };
+}
diff --git a/frontend/src/sheets/__tests__/formulaBox.test.ts b/frontend/src/sheets/__tests__/formulaBox.test.ts
new file mode 100644
index 00000000..ad5b1a65
--- /dev/null
+++ b/frontend/src/sheets/__tests__/formulaBox.test.ts
@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { wordsOf, sampleLine, insertGroups, levelTokens, shapesOf, writeShape } from '../formulaBox';
+import type { Definition } from '../systemsApi';
+
+/**
+ * The formula box as logic (formula box 1; approved mockup docs/mockups/formula-box.html,
+ * 2026-10-29): a formula said in words, its sample line, what INSERT offers (no formulas for an
+ * amount), and the SHAPES and what each writes.
+ */
+const DEF = {
+  format: 1, name: 'Hearth',
+  stats: [{ id: 'abilities', label: 'ABILITIES', stats: [{ id: 'str', label: 'Strength' }, { id: 'con', label: 'Constitution' }] }],
+  derived: [{ id: 'con_mod', label: 'CON modifier', formula: 'floor(@con / 2)' }],
+  lookups: { mod: { bands: [{ value: 0 }] } },
+  choices: [
+    { id: 'classes', one: 'Class', many: 'Classes', levelled: true, options: [{ id: 'fighter', label: 'Fighter', features: [] }] },
+    { id: 'feats', one: 'Feat', many: 'Feats', options: [] },
+  ],
+} as unknown as Definition;
+const LEVEL = [{ id: 'level', label: 'Level', value: 3 }];
+
+describe('a formula in words', () => {
+  it('says the common shapes of an amount plainly', () => {
+    expect(wordsOf('amount', '5')).toBe('+5, always');
+    expect(wordsOf('amount', '-1')).toBe('−1, always');
+    expect(wordsOf('amount', '2 * @level', LEVEL)).toBe('+2 for each level');
+    expect(wordsOf('amount', '@level * 2', LEVEL)).toBe('+2 for each level');
+    expect(wordsOf('amount', '@con', [{ id: 'con', label: 'Constitution', value: 14 }])).toBe('+ your Constitution');
+    expect(wordsOf('amount', 'floor(@level / 2)', LEVEL)).toBe('+ half your level, rounded down');
+  });
+
+  it('says anything else by what it is worked out from, by label, ids while the server hasn\'t answered', () => {
+    expect(wordsOf('amount', '@str + @level', [{ id: 'str', label: 'Strength', value: 16 }, ...LEVEL])).toBe('worked out from Strength, Level');
+    expect(wordsOf('amount', '2 * @level')).toBe('+2 for each level');
+    expect(wordsOf('amount', '1 + 2')).toBe('a fixed number');
+    expect(wordsOf('amount', '3 * @fighter_level + @con')).toBe('worked out from fighter_level, con');
+    expect(wordsOf('amount', '   ')).toBe('');
+  });
+
+  it('says uses in uses', () => {
+    expect(wordsOf('uses', '1')).toBe('1 use, always');
+    expect(wordsOf('uses', '3')).toBe('3 uses, always');
+    expect(wordsOf('uses', '1 * @level', LEVEL)).toBe('1 for each level');
+    expect(wordsOf('uses', '@con_mod', [{ id: 'con_mod', label: 'CON modifier', value: 2 }])).toBe('as many as your CON modifier');
+  });
+
+  it('says what a requirement needs', () => {
+    const str = [{ id: 'str', label: 'Strength', value: 16 }];
+    expect(wordsOf('requires', '@str >= 13', str)).toBe('needs Strength 13 or more');
+    expect(wordsOf('requires', '@str > 12', str)).toBe('needs Strength over 12');
+    expect(wordsOf('requires', '@str >= 13 and @level >= 2', [...str, ...LEVEL])).toBe('needs Strength >= 13 and Level >= 2');
+  });
+});
+
+describe('the sample line', () => {
+  it('says what it comes to for the sample, with each name read', () => {
+    expect(sampleLine('amount', { ok: true, value: 6, reads: LEVEL })).toBe('sample Level 3: +6');
+    expect(sampleLine('amount', { ok: true, value: -1, reads: [] })).toBe('−1');
+    expect(sampleLine('uses', { ok: true, value: 1, reads: LEVEL })).toBe('sample Level 3: 1 use');
+    expect(sampleLine('uses', { ok: true, value: 2.5, reads: [] })).toBe('2.5 uses');
+    expect(sampleLine('amount', { ok: true, value: 6, reads: [...LEVEL, ...LEVEL] })).toBe('sample Level 3: +6');
+  });
+
+  it('says whether the sample meets a requirement', () => {
+    expect(sampleLine('requires', { ok: true, value: 1, reads: [{ id: 'str', label: 'Strength', value: 16 }] })).toBe('the sample (Strength 16) meets it');
+    expect(sampleLine('requires', { ok: true, value: 0, reads: [] })).toBe('the sample doesn\'t meet it');
+  });
+});
+
+describe('INSERT', () => {
+  it('offers levels, stats, formulas, tables and workings, with what each is', () => {
+    const groups = insertGroups(DEF, 'requires');
+    expect(groups.map((g) => g.title)).toEqual(['LEVELS', 'STATS', 'FORMULAS', 'TABLES', 'WORKINGS']);
+    expect(groups[0].items).toEqual([
+      { token: '@level', label: 'LEVEL' }, { token: '@classes_level', label: 'CLASSES LEVEL' }, { token: '@fighter_level', label: 'FIGHTER LEVEL' },
+    ]);
+    expect(groups[2].items).toEqual([{ token: '@con_mod', label: 'CON MODIFIER' }]);
+    expect(groups[3].items).toEqual([{ token: 'mod()', label: 'A TABLE' }]);
+    expect(groups[4].items).toContainEqual({ token: 'floor()', label: 'ROUNDED DOWN' });
+  });
+
+  it('offers an amount no formulas, which it can\'t read', () => {
+    expect(insertGroups(DEF, 'amount').map((g) => g.title)).toEqual(['LEVELS', 'STATS', 'TABLES', 'WORKINGS']);
+  });
+
+  it('has no levels without a levelled list, and no @level when a stat is called that', () => {
+    expect(levelTokens({ ...DEF, choices: [] } as Definition)).toEqual([]);
+    const own = { ...DEF, stats: [{ id: 'g', label: 'G', stats: [{ id: 'level', label: 'Level' }] }] } as unknown as Definition;
+    expect(levelTokens(own).map((l) => l.token)).toEqual(['@classes_level', '@fighter_level']);
+  });
+});
+
+describe('SHAPES', () => {
+  it('offers amounts and uses four, requirements two', () => {
+    expect(shapesOf(DEF, 'amount').map((s) => [s.label, s.asks])).toEqual([
+      ['A NUMBER', 'number'], ['PER LEVEL', 'number'], ['PER CLASS LEVEL', 'number-and-level'], ['HALF LEVEL', 'none'],
+    ]);
+    expect(shapesOf(DEF, 'requires').map((s) => [s.label, s.asks])).toEqual([['AT LEAST', 'number-and-stat'], ['LEVEL AT LEAST', 'number-and-level']]);
+    expect(shapesOf(DEF, 'amount').every((s) => !s.needs)).toBe(true);
+  });
+
+  it('says why a shape can\'t be used yet', () => {
+    const bare = { format: 1, name: 'B' } as Definition;
+    expect(shapesOf(bare, 'amount').map((s) => s.needs)).toEqual([undefined, 'No levels yet: make a list levelled on CHOICES', 'No levels yet: make a list levelled on CHOICES', 'No levels yet: make a list levelled on CHOICES']);
+    expect(shapesOf(bare, 'requires')[0].needs).toBe('No stats yet: make them on STATS & RULES');
+  });
+
+  it('writes each shape', () => {
+    expect(writeShape('number', 5)).toBe('5');
+    expect(writeShape('per_level', 2)).toBe('2 * @level');
+    expect(writeShape('per_class_level', 2, '@fighter_level')).toBe('2 * @fighter_level');
+    expect(writeShape('half_level', 9)).toBe('floor(@level / 2)');
+    expect(writeShape('at_least', 13, '@str')).toBe('@str >= 13');
+    expect(writeShape('level_at_least', 5, '@level')).toBe('@level >= 5');
+    expect(writeShape('number', Number.NaN)).toBe('0');
+    expect(writeShape('number', 2.7)).toBe('2');
+    expect(writeShape('nonsense', 1)).toBe('');
+  });
+});
diff --git a/frontend/src/sheets/builderHelp.ts b/frontend/src/sheets/builderHelp.ts
index 7d27e1ba..08986dcb 100644
--- a/frontend/src/sheets/builderHelp.ts
+++ b/frontend/src/sheets/builderHelp.ts
@@ -213,13 +213,13 @@ export const HINTS = {
   'choices.options': 'What a character can pick from this list. A big list, like forty feats, is fine: up to a hundred.',
   'choices.optionName': 'What players see for this option: SOLDIER, DOCKHAND, TOUGH.',
   'choices.description': 'Words for the table about this option, shown when a player picks.',
-  'choices.requires': 'Optional. A formula that must not be 0 for this to be picked, like @int >= 13. One not met shows greyed with the reason; the GM can pick it anyway.',
+  'choices.requires': 'Optional. A formula that must not be 0 for this to be picked, like @int >= 13. One not met shows greyed with the reason; the GM can pick it anyway. The line under it says it in words and whether the sample character meets it; the formula button beside it writes common ones for you and lists the names it can read.',
   'choices.features': 'What this pick gives a character, each unlocking at a level in a levelled list. One feature can do several things at once, or be words for the table.',
   'choices.featureName': 'What players see for this feature on their sheet: GUARD STANCE, RALLY.',
   'choices.at': 'The pick\'s level this feature unlocks at: a SOLDIER 3 has every feature at 1, 2 and 3.',
   'choices.text': 'Words for the table: what the feature means in play, shown on the sheet.',
-  'choices.modifiers': 'Adds to a stat, a formula or a health field, by a number or a formula like @mage_level. A stat stays as the player typed it; formulas and rolls read it with this added. An amount reads stats and levels, never a formula.',
-  'choices.uses': 'Uses the player ticks off on the sheet, as many as a number or a formula, refilled by one of the system\'s rests. With none picked, the GM refills them.',
+  'choices.modifiers': 'Adds to a stat, a formula or a health field, by a number or a formula like @mage_level. A stat stays as the player typed it; formulas and rolls read it with this added. An amount reads stats and levels, never a formula. The line under it says it in words with what it comes to for the sample character; the formula button beside it writes common ones for you (PER LEVEL...) and lists the names it can read.',
+  'choices.uses': 'Uses the player ticks off on the sheet, as many as a number or a formula, refilled by one of the system\'s rests. With none picked, the GM refills them. The line under the number says how many the sample character gets; the formula button beside it writes common ones for you.',
   'choices.rolls': 'Rolls from STATS & RULES this feature gives, like a spell or a special attack.',
   'choices.changes': 'One of a roll\'s changes this feature lets the character take, like ADVANTAGE on a save.',
   'choices.choice': 'Another list to pick from once this unlocks: a specialty at level 3, a spell, a feat.',
diff --git a/frontend/src/sheets/formulaBox.ts b/frontend/src/sheets/formulaBox.ts
new file mode 100644
index 00000000..7420bccc
--- /dev/null
+++ b/frontend/src/sheets/formulaBox.ts
@@ -0,0 +1,139 @@
+// The builder's formula box, as logic (formula box 1; approved mockup docs/mockups/formula-box.html,
+// 2026-10-29): what a formula says in words, the line its sample value is told in, the SHAPES that
+// write a common one for you, and the names INSERT offers. The server reads the formula itself
+// (POST /api/systems/preview-formulas, the game's own parser) and says what it reads; nothing here
+// parses. Pure, so the box (components/FormulaBox.tsx) only draws.
+
+import type { Definition } from './systemsApi';
+import { allStats, formulaList, tableList, FUNCTIONS } from './statsRules';
+import { choiceLists } from './choices';
+
+/** What a box holds: a modifier's amount, an option's requirement, a feature's uses. */
+export type FormulaKind = 'amount' | 'requires' | 'uses';
+
+/** One name a formula reads, as the server worked it out for the sample. */
+export interface FormulaReads { id: string; label: string; value: number }
+/** What the server made of a formula (backend systemBuilder/formulaPreview.js). */
+export type FormulaRead = { ok: true; value: number; reads: FormulaReads[] } | { ok: false; problem: string; name?: string; suggest?: string };
+
+const signed = (n: number) => (n < 0 ? `−${-n}` : `+${n}`);
+const word = (id: string, reads: FormulaReads[]) => reads.find((r) => r.id === id)?.label ?? id;
+
+/**
+ * A formula in words: a few common shapes said plainly (+2 for each level, + half your level,
+ * needs Strength 13 or more), anything else by what it is worked out from. Empty for an empty box.
+ */
+export const wordsOf = (kind: FormulaKind, text: string, reads: FormulaReads[] = []): string => {
+  const t = text.trim();
+  if (!t) return '';
+  let m: RegExpMatchArray | null;
+  const named = () => {
+    // By label once the server has said; until then, the @names as written.
+    const names = [...new Set(reads.length ? reads.map((r) => r.label) : [...t.matchAll(/@([a-z][a-z0-9_]*)/g)].map((x) => x[1]))];
+    return names.length ? `worked out from ${names.join(', ')}` : 'a fixed number';
+  };
+  if (kind === 'requires') {
+    if ((m = t.match(/^@([a-z][a-z0-9_]*)\s*>=\s*(-?\d+)$/))) return `needs ${word(m[1], reads)} ${m[2]} or more`;
+    if ((m = t.match(/^@([a-z][a-z0-9_]*)\s*>\s*(-?\d+)$/))) return `needs ${word(m[1], reads)} over ${m[2]}`;
+    return `needs ${t.replace(/@([a-z][a-z0-9_]*)/g, (_, id: string) => word(id, reads))}`;
+  }
+  const unit = kind === 'uses' ? (n: string) => `${n} use${n === '1' ? '' : 's'}` : (n: string) => signed(Number(n));
+  if ((m = t.match(/^(-?\d+)$/))) return `${unit(m[1])}, always`;
+  // N * @name, or @name * N.
+  const per = t.match(/^(\d+)\s*\*\s*@([a-z][a-z0-9_]*)$/) ?? t.match(/^@([a-z][a-z0-9_]*)\s*\*\s*(\d+)$/);
+  if (per) {
+    const [n, id] = /^\d+$/.test(per[1]) ? [per[1], per[2]] : [per[2], per[1]];
+    return `${kind === 'uses' ? n : signed(Number(n))} for each ${word(id, reads).toLowerCase()}`;
+  }
+  if ((m = t.match(/^@([a-z][a-z0-9_]*)$/))) return `${kind === 'uses' ? 'as many as' : '+'} your ${word(m[1], reads)}`;
+  if ((m = t.match(/^floor\(\s*@([a-z][a-z0-9_]*)\s*\/\s*2\s*\)$/))) return `${kind === 'uses' ? 'half' : '+ half'} your ${word(m[1], reads).toLowerCase()}, rounded down`;
+  return named();
+};
+
+/** What it comes to for the sample: `sample Level 3: +6`, `the sample (Strength 16) meets it`, `sample: 3 uses`. */
+export const sampleLine = (kind: FormulaKind, read: FormulaRead & { ok: true }): string => {
+  const names = [...new Map(read.reads.map((r) => [r.id, `${r.label} ${r.value}`])).values()].join(', ');
+  if (kind === 'requires') return `the sample${names ? ` (${names})` : ''} ${read.value !== 0 ? 'meets it' : 'doesn\'t meet it'}`;
+  const v = Math.round(read.value * 100) / 100;
+  const said = kind === 'uses' ? `${v} use${v === 1 ? '' : 's'}` : signed(v);
+  return names ? `sample ${names}: ${said}` : said;
+};
+
+/** One list of names INSERT offers, under a title. */
+export interface InsertGroup { title: string; items: { token: string; label: string }[] }
+
+/** The level names formulas read: @level (unless a stat or formula has that id), each levelled list's sum, each option's. */
+export const levelTokens = (def: Definition): { token: string; label: string }[] => {
+  const levelled = choiceLists(def).filter((c) => c.levelled === true);
+  if (!levelled.length) return [];
+  const taken = new Set([...allStats(def).map((s) => s.id), ...formulaList(def).map((f) => f.id)]);
+  return [
+    ...(taken.has('level') ? [] : [{ token: '@level', label: 'LEVEL' }]),
+    ...levelled.flatMap((c) => [
+      { token: `@${c.id}_level`, label: `${(c.many || c.id).toUpperCase()} LEVEL` },
+      ...c.options.map((o) => ({ token: `@${o.id}_level`, label: `${(o.label || o.id).toUpperCase()} LEVEL` })),
+    ]),
+  ];
+};
+
+/** WORKINGS: the functions, with what each does. */
+const WORKINGS: Record<string, string> = {
+  floor: 'ROUNDED DOWN', ceil: 'ROUNDED UP', round: 'ROUNDED', min: 'THE SMALLER', max: 'THE LARGER', abs: 'WITHOUT ITS SIGN', clamp: 'KEPT BETWEEN', if: 'ONE OR THE OTHER',
+};
+
+/**
+ * What INSERT offers a box: its levels, stats, formulas (never for an amount, which reads the sheet
+ * as typed and levels), tables and the workings. Empty groups left out.
+ */
+export const insertGroups = (def: Definition, kind: FormulaKind): InsertGroup[] => [
+  { title: 'LEVELS', items: levelTokens(def) },
+  { title: 'STATS', items: allStats(def).map((s) => ({ token: `@${s.id}`, label: (s.label || s.id).toUpperCase() })) },
+  { title: 'FORMULAS', items: kind === 'amount' ? [] : formulaList(def).map((f) => ({ token: `@${f.id}`, label: (f.label || f.id).toUpperCase() })) },
+  { title: 'TABLES', items: tableList(def).map((t) => ({ token: `${t.id}()`, label: 'A TABLE' })) },
+  { title: 'WORKINGS', items: FUNCTIONS.map((fn) => ({ token: `${fn}()`, label: WORKINGS[fn] ?? '' })) },
+].filter((g) => g.items.length);
+
+/** A SHAPE: a common formula written for you from a number, and a name where it needs one. */
+export interface Shape {
+  id: string; label: string;
+  /** What it asks before writing: a number, a number and which level or stat, or nothing. */
+  asks: 'number' | 'none' | 'number-and-level' | 'number-and-stat';
+  /** Why it can't be used yet, when it can't. */
+  needs?: string;
+}
+
+/**
+ * The shapes a box offers. Amounts and uses: A NUMBER, PER LEVEL, PER CLASS LEVEL, HALF LEVEL;
+ * requirements: AT LEAST (a stat) and LEVEL AT LEAST. A shape needing levels or stats says so
+ * when the system has none.
+ */
+export const shapesOf = (def: Definition, kind: FormulaKind): Shape[] => {
+  const levels = levelTokens(def).length ? undefined : 'No levels yet: make a list levelled on CHOICES';
+  const stats = allStats(def).length ? undefined : 'No stats yet: make them on STATS & RULES';
+  if (kind === 'requires') {
+    return [
+      { id: 'at_least', label: 'AT LEAST', asks: 'number-and-stat', needs: stats },
+      { id: 'level_at_least', label: 'LEVEL AT LEAST', asks: 'number-and-level', needs: levels },
+    ];
+  }
+  return [
+    { id: 'number', label: 'A NUMBER', asks: 'number' },
+    { id: 'per_level', label: 'PER LEVEL', asks: 'number', needs: levels },
+    { id: 'per_class_level', label: 'PER CLASS LEVEL', asks: 'number-and-level', needs: levels },
+    { id: 'half_level', label: 'HALF LEVEL', asks: 'none', needs: levels },
+  ];
+};
+
+/** The text a shape writes, from its number and the name picked (a level or a stat, `@id` form). */
+export const writeShape = (shape: string, n: number, name = '@level'): string => {
+  const k = Number.isFinite(n) ? Math.trunc(n) : 0;
+  switch (shape) {
+    case 'number': return String(k);
+    case 'per_level': return `${k} * @level`;
+    case 'per_class_level': return `${k} * ${name}`;
+    case 'half_level': return 'floor(@level / 2)';
+    case 'at_least': return `${name} >= ${k}`;
+    case 'level_at_least': return `${name} >= ${k}`;
+    default: return '';
+  }
+};
diff --git a/frontend/src/sheets/systemsApi.ts b/frontend/src/sheets/systemsApi.ts
index 7906debe..ea20c5cf 100644
--- a/frontend/src/sheets/systemsApi.ts
+++ b/frontend/src/sheets/systemsApi.ts
@@ -6,6 +6,7 @@
 import type { InstallMode, InstallPreview, InstallResult, LibrarySystem } from './systemsLibrary';
 import type { PublishPreview } from './versionPreview';
 import type { ImportPreview } from './choicesImport';
+import type { FormulaKind, FormulaRead } from './formulaBox';
 import type { CustomRenderSheet } from './customTemplates';
 import type { GameCondition } from './tokenConditions';
 import type { TableEntry } from './tableConditions';
@@ -163,6 +164,9 @@ export const systemsApi = (token: string, fetcher: typeof fetch = fetch) => {
      */
     previewValues: (definition: Definition) =>
       call<{ values: Record<string, number>; problems: Problem[] }>(fetcher, token, '/api/systems/preview-values', 'POST', { definition }),
+    /** The formula box (formula box 1): each formula read as the game reads it, for the sample character. */
+    previewFormulas: (definition: Definition, formulas: { text: string; kind: FormulaKind }[]) =>
+      call<{ results: FormulaRead[]; sampleLevel: number }>(fetcher, token, '/api/systems/preview-formulas', 'POST', { definition, formulas }),
     /**
      * TEST ROLL (6b1a): one of a draft's rolls made for its sample character by the table's own
      * engine, for `fieldId` or the first field it is rolled by, with the changes picked. Changes

From 3bdb13b673d3427dc5428a4b96f5a258e9d7b0b4 Mon Sep 17 00:00:00 2001
From: Developer <dev@example.com>
Date: Thu, 29 Oct 2026 21:08:27 -0500
Subject: [PATCH 2/2] test: the formula box journey waits for the draft to say
 SAVED before reading it (autosave is 5s, CI is slower)

---
 e2e/tests/builder-formula-box.spec.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/e2e/tests/builder-formula-box.spec.ts b/e2e/tests/builder-formula-box.spec.ts
index 4e524214..9583d886 100644
--- a/e2e/tests/builder-formula-box.spec.ts
+++ b/e2e/tests/builder-formula-box.spec.ts
@@ -63,10 +63,10 @@ test('the formula box says a formula in words, catches a misspelt name, and writ
   await expect(fighter.getByRole('textbox', { name: 'REQUIRES' })).toHaveValue('@str >= 13');
   await expect(fighter.getByTestId('formula-words')).toHaveText('needs Strength 13 or more · the sample (Strength 16) meets it');
 
-  // Saved as written, with no problems.
-  await expect.poll(async () => {
-    const { draft } = await asGm(request, token, 'get', `/api/systems/${id}`);
-    return [draft.choices[1].options[0].features[0].modifiers[0].amount, draft.choices[0].options[0].requires];
-  }).toEqual(['3 * @fighter_level + @con', '@str >= 13']);
-  expect((await asGm(request, token, 'get', `/api/systems/${id}`)).problems).toEqual([]);
+  // Saved as written, with no problems: the draft saves itself a few seconds after the last change.
+  await expect(page.getByTestId('save-status')).toHaveText(/· SAVED /, { timeout: 15_000 });
+  const { draft, problems } = await asGm(request, token, 'get', `/api/systems/${id}`);
+  expect([draft.choices[1].options[0].features[0].modifiers[0].amount, draft.choices[0].options[0].requires])
+    .toEqual(['3 * @fighter_level + @con', '@str >= 13']);
+  expect(problems).toEqual([]);
 });