react-expert

Related skills: react-vm, atom-state, react-composition

<react-mind>

<vm-architecture>
VM :: DomainInput -> UIReadyOutput
Component :: UIReadyOutput -> ReactElement

Component ≡ pure(render)
VM ≡ state + logic + effects

vm-boundary := atoms-only-in-vm
component-boundary := subscribe + invoke + match + render
</vm-architecture>

<vm-philosophy>
-- VMs are presentational adapters, not logic containers

VM :: Capabilities -> Presentation
VM =/= Logic

-- VMs COMPOSE capabilities, they don't IMPLEMENT logic
vm :: { cap1, cap2, ... } -> { derived1, derived2, actions }

ownLogic      :: VM -> bottom        -- VMs never own business logic
compose       :: VM -> valid         -- VMs wire capabilities together
derivePresent :: VM -> valid         -- VMs compute what to display

-- Logic lives in services/capabilities
-- VMs are the presentational glue layer

<laws>
separation:    logic in Service; presentation in VM
composition:   VM = compose(Service1, Service2, ...)
delegation:    vm.action -> service.operation
derivation:    vm.derived$ = f(service.state$)
</laws>

<anti-patterns>
VM { compute, transform, validate }     -- logic in VM
VM { businessRule, domainCalc }         -- domain logic in VM
VM { httpCall, dbQuery }                -- infrastructure in VM
</anti-patterns>

<patterns>
VM { useCapability, deriveView }        -- VM composes
VM { format(cap.data$), cap.submit }    -- VM presents + delegates
VM { map(state$, toDisplayFormat) }     -- VM transforms for UI
</patterns>

<example>
-- Wrong: VM owns logic
vm = {
  validate :: Input -> Boolean           -- belongs in ValidationService
  calculate :: Data -> Result            -- belongs in CalculationService
  transform :: A -> B                    -- belongs in TransformService
}

-- Correct: VM composes capabilities
vm :: { ValidationService, CalculationService } -> {
  isValid$ = pipe(input$, Atom.map(ValidationService.check))
  result$ = pipe(data$, Atom.map(CalculationService.compute))
  submit = () -> ValidationService.validate >> CalculationService.run
}
</example>
</vm-philosophy>

<reactive-state>
Atom[A] := reactive(A)
Atom.map :: Atom[A] -> (A -> B) -> Atom[B]
Atom.fn :: (I, Get) -> Effect[O] -> Atom.Fn[I, Result[O]]

derived$ := pipe(source$, Atom.map(transform))
action := Atom.fn((_, get) => Effect.gen(...))

Result.matchWithWaiting :: Result[A, E] -> { onWaiting, onSuccess, onError, onDefect } -> B
Result.match :: Result[A, E] -> { onInitial, onSuccess, onFailure } -> B
</reactive-state>

<state-machine>
State := Data.TaggedEnum<{ Idle: {}, Loading: {}, Success: { data: A }, Error: { error: E } }>

transition :: State -> Event -> State
render :: State -> $match(state, handlers)
</state-machine>

<agent>
Agent :: Skills -> Context -> Problem -> E[Solution]

<laws>
knowledge-first:    forall p. act(p) requires gather(skills(p)) ^ gather(context(p))
no-assumption:      assume(k) -> invalid; ensure(k) -> valid
completeness:       solution(p) requires forall s in skills(p). invoked(s)
identity:           Agent(empty) = empty
homomorphism:       Agent(p1 . p2) = Agent(p1) . Agent(p2)
idempotence:        verified(s) -> Agent(Agent(p)) = Agent(p)
totality:           forall p. Agent(p) in {Solution, Unsolvable, NeedSkill}
exhaustive-match:   handle(adt) -> $match(adt, { Tag1: h1, Tag2: h2, ..., Tagn: hn })
no-conditionals:    if x._tag === "A" not-valid; $match(x, {...}) valid

vm-composes:        Component = pure(render); VM = compose(capabilities) + derive(presentation)
atoms-in-vm:        define(atom) requires inside(Layer.effect(VMTag, ...))
no-boolean-props:   <C flag1 flag2 /> not-valid; compose(<C.Variant />) valid
no-useEffect:       useEffect(sideEffect) -> vm.action(); useEffect(derived) -> vm.derived$
</laws>

<acquire>
acquire :: Problem -> E[(Skills, Context)]
acquire problem = do
  skill-needs   <- analyze(problem, "skills")
  context-needs <- analyze(problem, "context")
  skills  <- for need in skill-needs: invoke(dispatch(need))
  context <- for need in context-needs: read/module/grep(need)
  pure(skills, context)
</acquire>

<loop>
loop :: E[(), never, empty]
loop = do
  (skills, context) <- acquire(problem)
  patterns <- identify(problem, context)
  for pattern in patterns:
    | not vm-composes(pattern)     -> extract(logic, service); compose(vm, service)
    | not atoms-in-vm(pattern)     -> move(atoms, vm-layer)
    | not no-boolean-props(pattern) -> refactor(composition)
    | not no-useEffect(pattern)    -> migrate(effect, vm)
    | not exhaustive-match(pattern) -> apply($match)
  solution <- synthesize(transforms, skills, context)
  verified <- verify(solution)
  emit(verified)
</loop>

<transforms>
logic-in-component   -> extract-to-service; compose-in-vm
format(data)         -> vm.formatted$
derive(value)        -> pipe(source$, Atom.map(f))
boolean-prop         -> composition-pattern
useEffect(fetch)     -> Atom.fn + Result.matchWithWaiting
useEffect(subscribe) -> Atom.subscriptionRef
useEffect(listener)  -> Atom.make + get.addFinalizer
useState(value)      -> Atom.make(value)
conditional-render   -> $match(state, handlers)
</transforms>

<skills>
dispatch :: Need -> Skill
dispatch = \need -> case need of
  need(vm-pattern)       -> /react-vm
  need(atom-state)       -> /atom-state
  need(composition)      -> /react-composition
  need(state-machine)    -> /pattern-matching
  need(effect-service)   -> /service-implementation
</skills>

<invariants>
forall output:
  vm-composes-not-owns
  ^ logic-in-services
  ^ atoms-defined-in-layer
  ^ zero-boolean-props
  ^ no-useEffect-for-logic
  ^ exhaustive-pattern-match
  ^ actions-return-void
  ^ state-machines-as-TaggedEnum
  ^ Result-for-async-state
</invariants>
</agent>

<file-structure>
Component/
  Component.tsx      := pure-renderer
  Component.vm.ts    := interface + tag + layer
  index.ts           := re-exports

vm-file := {
  interface VMName {
    readonly state$: Atom[State]
    readonly derived$: Atom[Derived]
    readonly action: () => void
  }
  const VMName = Context.GenericTag<VMName>("VMName")
  const layer = Layer.effect(VMName, Effect.gen(...))
  export default { tag: VMName, layer }
}
</file-structure>

<patterns>

<vm-layer>
Layer.effect(VMTag, Effect.gen(function* () {
  const registry = yield* AtomRegistry

  const state$ = Atom.make(initialState)
  const derived$ = pipe(state$, Atom.map(transform))

  const action = () => {
    registry.set(state$, newValue)
  }

  return { state$, derived$, action }
}))
</vm-layer>

<atom-fn>
const submitAtom = Atom.fn((_: void, get) =>
  Effect.gen(function* () {
    const value = get(input$)
    get.set(input$, "")
    yield* service.submit(value)
  }).pipe(Effect.provide(Dependencies))
)
</atom-fn>

<subscription-ref>
const history$ = Atom.subscriptionRef(session.state.history)
void registry.mount(history$)
</subscription-ref>

<component-integration>
function Component() {
  const vmResult = useVM(VM.tag, VM.layer)

  return Result.match(vmResult, {
    onInitial: () => <Spinner />,
    onSuccess: ({ value: vm }) => <Content vm={vm} />,
    onFailure: ({ cause }) => <Error cause={cause} />
  })
}

function Content({ vm }: { vm: VMType }) {
  const state = useAtomValue(vm.state$)
  return State.$match(state, {
    Idle: () => null,
    Loading: () => <Spinner />,
    Success: ({ data }) => <Display data={data} />,
    Error: ({ error }) => <Alert>{error}</Alert>
  })
}
</component-integration>

<composition-over-boolean>
<UserForm isUpdate hideWelcome showEmail /> not-valid

<UpdateUserForm>
  <UserForm.NameField />
  <UserForm.SaveButton />
</UpdateUserForm> valid
</composition-over-boolean>

<avoid-useEffect>
useEffect(fetch)     -> vm: Atom.fn + Result.matchWithWaiting
useEffect(subscribe) -> vm: Atom.subscriptionRef + registry.mount
useEffect(listener)  -> vm: Atom.make with get.addFinalizer
useEffect(derive)    -> vm: pipe(source$, Atom.map(f))
useEffect(reset)     -> component: key={id}
</avoid-useEffect>

</patterns>

<quality-checklist>
- [ ] Parent component has Component.tsx + Component.vm.ts
- [ ] VM file has: interface, tag, default { tag, layer } export
- [ ] Atoms only defined inside Layer.effect
- [ ] Atom names use camelCase$ suffix
- [ ] Child components receive VM as prop (no own VM)
- [ ] Zero boolean props (use composition)
- [ ] Zero logic in components (formatting, conditions, computations)
- [ ] Zero business logic in VMs (validation, computation, domain rules)
- [ ] Logic lives in services/capabilities, VMs compose them
- [ ] VM produces all UI-ready values (derived from capabilities)
- [ ] Actions return void
- [ ] State machines use Data.TaggedEnum
- [ ] Pattern match with $match in components
- [ ] No useEffect for side effects (VM handles)
- [ ] Result.matchWithWaiting for Atom.fn async states
- [ ] Result.match for VM initialization
</quality-checklist>

</react-mind>