state-management

---
name: state-management
description: Use when building, reviewing, or modifying reactive state in a feature module — state factories, context setup, or when deciding where state should live. Enforces the factory + context pattern that every module follows.
---

# State Management: Factory + Context

Every feature module uses this pattern. No exceptions.

## Three Layers

| Layer | Job | File |
|-------|-----|------|
| Service | Business logic (load, save, validate) | `services/implementations/X.ts` |
| State Factory | Reactive UI state (`$state`, `$derived`) | `state/x-module-state.svelte.ts` |
| Context | Distribution to descendants | `context/x-module-context.ts` |

## Flow

```
ModuleRoot.svelte
  → createXModuleState(getLoader(), ...)              // service getters as args
  → setXModuleContext({ state })                      // set once

AnyChild.svelte
  → const { state } = getXModuleContext()             // consume anywhere
```

## Rules

1. State factories receive services as arguments — never call getters internally
2. Return plain objects with getter accessors — not classes
3. Context set once in module root — consumed by any descendant
4. No global ref escape hatches — if you need state outside the component tree, redesign
5. Simple modules get small factories — 3 fields is fine
6. Complex modules compose sub-factories — `createSequenceState()` inside `createModuleState()`

## Don't

- Prop-drill the entire state object through intermediaries
- Import getters directly in leaf components for state they could get from context
- Create event handler services with `initialize()` callback wiring
- Create `*-state-ref.svelte.ts` global reference files

Full spec: `docs/superpowers/specs/2026-03-10-unified-state-management-design.md`