docs: write down how to model a feature's state, and lint the checkable part (#14472)

Writes down the state-modelling conventions we keep re-explaining in
review, and
adds one lint rule for the part that is mechanically checkable.

### Why

Reviews of anything with a beginning and an end — a wizard, an upload,
an
onboarding flow — keep converging on the same handful of points: several
independent booleans that must agree, values stored that could be
derived, and
effects used to keep two pieces of internal state in sync rather than to
talk to
something outside the app. Each time it gets re-argued from scratch on
the PR,
which is slow for the reviewer and unpleasant for the author, who
reasonably
asks why nobody said so earlier.

`docs/guidance/state-and-effects.md` is glob-loaded on `src/**/*.ts` and
`src/**/*.vue`, so it applies automatically rather than needing to be
found.

### What it says

One state value as a discriminated union instead of N booleans, named
events
rather than assignment scattered across call sites, a pure transition
function so
one place owns the rules, `computed` for anything derivable, and effects
reserved
for synchronising outward. Plus the Vue mapping — state to Pinia,
transition to a
pure function, derivation to `computed`, synchronisation to `watch`.

It deliberately does **not** recommend a state-machine library. There is
no
XState or `createMachine` precedent anywhere in `src/`, and a
hand-rolled union
with a pure `reduce` gets the same guarantees without the dependency.

### The lint rule

`no-restricted-syntax` flagging `getBoundingClientRect`,
`getComputedStyle` and
`querySelector*` inside a `computed`. A derivation that measures the DOM
runs a
layout read on every recompute and cannot be unit-tested without a
browser.

It ships at **`warn`, not `error`**, because there are exactly four
pre-existing
instances and this PR does not fix them:

| File | Count |
| ---- | ----- |
| `src/components/maskeditor/BrushCursor.vue` | 2 |
| `src/components/breadcrumb/SubgraphBreadcrumb.vue` | 1 |
| `src/components/topbar/WorkflowTabs.vue` | 1 |

Promote to `error` once those derive from stores instead. I verified the
count
against `main` at the current head rather than trusting the number I
first wrote.

### Scope

Docs and lint config only — no runtime code, no behaviour change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: christian-byrne

AGENTS.md

@@ -4,6 +4,7 @@ See @docs/guidance/\*.md for file-type-specific conventions (auto-loaded by glob
 
 - `docs/guidance/engineering.md` — general engineering guidelines, project philosophy, code-review checklist, external resource links
 - `docs/guidance/vue-components.md` — Vue 3 Composition API best practices
+- `docs/guidance/state-and-effects.md` — modelling a feature's state: one discriminated union, named events, a pure transition, effects reserved for synchronising outward
 - `docs/guidance/typescript.md` — TypeScript type-safety rules
 - `docs/guidance/vitest.md` — Vitest unit/component test conventions
 - `docs/guidance/playwright.md` — Playwright E2E conventions and API-mock typing table

docs/guidance/state-and-effects.md

@@ -0,0 +1,157 @@
+---
+globs:
+  - 'src/**/*.ts'
+  - 'src/**/*.vue'
+---
+
+# State, Effects and Workflows
+
+How to represent a multi-step process — onboarding, a wizard, an upload, a
+checkout, anything with a beginning and an end — in a reactive framework.
+
+> **Events initiate work. One explicit state represents the workflow. Pure
+> derivations shape the UI. Effects only synchronise with external systems.**
+
+This applies to any framework; the Vue mapping is at the bottom.
+
+## 1. One state, not several booleans
+
+Hold the **minimum authoritative facts** needed to render and continue. Anything
+computable from them is not state.
+
+Avoid independent booleans for what is really one value. Prefer a discriminated
+union, so invalid combinations are structurally impossible rather than merely
+unlikely.
+
+```ts
+// ✗ four facts that must agree, and nothing makes them
+const steps = ref<Step[]>([])
+const stepIdx = ref(-1)
+const waiting = ref(false)
+const active = ref<Flow | null>(null)
+
+// ✓ one fact
+type FlowState =
+  | { phase: 'idle' }
+  | { phase: 'awaiting'; flow: Flow; steps: Step[]; idx: number }
+  | { phase: 'showing'; flow: Flow; steps: Step[]; idx: number }
+  | { phase: 'finished'; flow: Flow; outcome: Outcome }
+```
+
+**The tell:** if ending the workflow means resetting four variables in the right
+order, it was one state and you gave it four variables.
+
+## 2. Change state through named events and a pure transition
+
+```ts
+type FlowEvent =
+  | { type: 'started'; flow: Flow; steps: Step[] }
+  | { type: 'advanced' }
+  | { type: 'skipped' }
+
+function reduceFlow(state: FlowState, event: FlowEvent): FlowState // pure switch
+```
+
+Invalid transitions become harmless — an event that means nothing in the current
+phase returns the state untouched — and valid ones become reviewable in one
+place. This is the same reason most frameworks recommend a reducer once
+state-update logic gets complex.
+
+It is also exhaustively testable: every state crossed with every event, including
+the pairs that should do nothing.
+
+## 3. Async orchestration belongs in commands
+
+Do **not** build chains where each step is an effect reacting to the last:
+
+```
+saving changed → effect saves → saved changed → effect invalidates
+              → invalidated changed → effect navigates
+```
+
+Nobody can read that as one sequence, and the middle of it is reachable from
+places you did not intend. Give the whole causal sequence to one function:
+
+```ts
+async function startFlow(id: string) {
+  const data = await load(id)
+  if (!data) return false
+  dispatch({ type: 'started', flow: id, steps: build(data) })
+  await settle()
+  dispatch({ type: 'stepEntered', idx: 0 })
+  return true
+}
+```
+
+## 4. Derive everything derivable
+
+Do not store `isOpening`, `canTransition`, `isLast`, or a second copy of data
+that already exists. If a `computed` can name it, do not put it in a `ref` and
+keep it in sync by hand — the sync is where the bugs live.
+
+## 5. Reserve effects for synchronising with the outside
+
+**Good effects** — one-way, outward, and they write nothing anything else reads:
+
+- state changed → emit telemetry
+- state changed → write a setting
+- component disposed → abort a request or unsubscribe
+- external socket event → _dispatch an event_ (not: assign state directly)
+
+**Bad effects:**
+
+- pointer target changed → recalculate steps
+- success changed → advance the workflow
+- an effect that writes state a second effect reads
+
+If two effects communicate through shared state, that is a transition wearing a
+disguise. Put it in the reducer.
+
+## 6. Do not inspect the DOM for something a store already knows
+
+Avoid `getBoundingClientRect`, `getComputedStyle`, and `document.querySelector`
+for positions and sizes that a store holds — especially inside a `computed`,
+where every recompute becomes a layout read.
+
+For canvas-anchored UI: `layoutStore` holds node bounds and `useTransformState`
+mirrors the camera, both reactive, so a screen rect is a **derivation** rather
+than a measurement. Floating UI accepts a
+[virtual element](https://floating-ui.com/docs/virtual-elements) for exactly
+this.
+
+Two caveats worth knowing rather than discovering:
+
+- `layoutStore` bounds are the node's **body box**. The element renders one
+  `NODE_TITLE_HEIGHT` above `position` and the resize tracker subtracts it, so
+  anything deriving a rect must add it back — and a collapsed node is exactly one
+  title tall, which is zero without it.
+- Node ids are **graph-local**. An id resolved against one graph names a
+  different node in another, so anything holding one across a workflow or
+  subgraph change must pin the graph it resolved against.
+
+## 7. Reach for a formal state machine when it earns it
+
+Parallel regions, nested states, timed transitions, cancellation, replay — at
+that point a library (XState or equivalent) buys real guarantees.
+
+Below it, a discriminated union plus a pure reducer is the same model without the
+dependency, and the migration between them is mechanical. **There is currently no
+XState in this repo**; introducing it is a deliberate decision, not a default.
+
+Note that two genuinely parallel regions — say a wizard's progress and a
+long-running job's outcome — should be two small states, not one product type.
+
+## Vue mapping
+
+| Concern               | Where it goes                                 |
+| --------------------- | --------------------------------------------- |
+| Workflow state        | `ref` / `shallowRef` in a Pinia store         |
+| Transition            | pure function, its own module, no Vue imports |
+| Derived UI            | `computed`                                    |
+| External sync         | `watch` / `watchEffect`                       |
+| The workflow itself   | store method (a command)                      |
+| Complex state machine | XState or equivalent                          |
+
+**Mental model:** user or external event → command performs async work → typed
+event → pure state transition → reactive derived UI. Effects sit _beside_ this
+loop, only to synchronise with external systems.

eslint.config.ts

@@ -302,6 +302,34 @@ export default defineConfig([
       ]
     }
   },
+  // A layout read inside a derivation runs on every recompute, and a derivation
+  // that measures the DOM cannot be tested without one. See
+  // docs/guidance/state-and-effects.md.
+  //
+  // 'warn' rather than 'error' because four pre-existing instances remain, in
+  // BrushCursor.vue, WorkflowTabs.vue and SubgraphBreadcrumb.vue. Promote to
+  // 'error' once those are derived from stores instead.
+  {
+    files: ['src/**/*.ts', 'src/**/*.vue'],
+    ignores: ['**/*.test.ts', '**/*.spec.ts'],
+    rules: {
+      'no-restricted-syntax': [
+        'warn',
+        {
+          selector:
+            "CallExpression[callee.name='computed'] CallExpression[callee.property.name='getBoundingClientRect']",
+          message:
+            'Do not measure the DOM inside a computed - every recompute becomes a layout read. Derive from a store instead. See docs/guidance/state-and-effects.md.'
+        },
+        {
+          selector:
+            "CallExpression[callee.name='computed'] CallExpression[callee.property.name=/^(getComputedStyle|querySelector|querySelectorAll)$/]",
+          message:
+            'Do not inspect the DOM inside a computed. Derive from a store instead. See docs/guidance/state-and-effects.md.'
+        }
+      ]
+    }
+  },
   {
     files: ['**/*.spec.ts'],
     ignores: ['browser_tests/tests/**/*.spec.ts', 'apps/*/e2e/**/*.spec.ts'],