A state-machine framework for the web.

Three frustrations drove this project. They show up everywhere in the modern frontend stack, and none of them get talked about as much as they should.

/ State coupled to UI

In most modern frameworks, your application's state lives inside the component tree. Hooks attach to components, providers wrap them, and stores subscribe to component instances.

Move a piece of business logic and you rewire components. Test a transition and you need a fake DOM. Refactor a feature and the blast radius is half the tree, because state boundaries and component boundaries got conflated.

State should be its own thing, not a property of where it happens to get read.

/ Shipping the renderer to the client

Most modern frameworks ship a JS bundle to the browser, fetch data over the network, and render the DOM there. The browser is the renderer of record.

That's complicated for no architectural reason. State has to sync between server and client, bundle size becomes a budget, and hydration mismatches become a class of bug. Loading, error, retry, and offline states pile up through the codebase.

It's also a security risk. Anything you ship to the browser is inspectable, and anything fetchable from it is replayable with different parameters. Server-side validation becomes load-bearing in a way that's easy to forget about until it bites you.

Render where state lives, and let browsers do what they're good at: displaying HTML.

/ The invisible RSC boundary

React Server Components ask you to keep components looking unified while execution quietly shifts between server and client. The intention is good.

The reality is that the boundary is load-bearing in ways that aren't visible from source. You discover where it actually fell by inspecting the bundle, or by reading the postmortem after secrets leaked into a client chunk. A "use client" directive at the top of a file is a long way from a guarantee about which code ran where.

A few rules, applied consistently. The unit of composition is the machine. Every machine declares where it runs (app scope or per session), what it reads, what it emits, and how it transitions.

Templates read machine state through explicit slots, and events round-trip to the server. The server diffs and returns just the slots that changed.

/ Machines, declared

// machines/cart.ts
import { defineMachine } from '@statorjs/stator/server'
import ProductsMachine from './products.ts'

export default defineMachine({
  name: 'CartMachine',
  lifecycle: 'session',            // 'app' | 'session'
  reads: [ProductsMachine],         // declared dependencies

  context: { items: [] },
  initial: 'idle',
  states: {
    idle: {
      on: {
        ADD_ITEM: { actions: 'addItem', emit: 'ITEM_ADDED' },
      },
    },
  },

  actions: {
    addItem: (ctx, ev, { reads }) => {
      // The canonical price is read from ProductsMachine on the server.
      // The wire event carries only productId.
      const product = reads.ProductsMachine.byId(ev.productId)
      if (!product) return
      ctx.items.push({
        productId: ev.productId,
        unitPrice: product.price,
        quantity: 1,
      })
    },
  },

  emits: {
    ITEM_ADDED: { payload: (ctx) => ({ items: ctx.items }) },
  },

  selectors: {
    itemCount: (ctx) => ctx.items.reduce((s, i) => s + i.quantity, 0),
  },
})

Templates read machine state through explicit slot helpers. A read call registers a binding the server can diff against on later transitions.

// templates/header.ts
import { html, read } from '@statorjs/stator/template'

export default function header(cart) {
  return html`<a href="/cart">Cart (${read(cart, c => c.itemCount)})</a>`
}

/ The wire edge

Every event arriving at the server is shape-validated before any machine sees it. The framework knows which machine the event targets, which route the client is on, and which slots that route's templates registered.

A single POST produces a small JSON patch list, set this slot's text, replace that list's innerHTML, changes this element's class. etc. The ~1kB client script applies each patch by element id.

No call-arbitrary-server-function or exposed RPC surface. Just send an event to a machine and let the machine decides what to do.

Stator has one rendering architecture: server renders HTML, client receives slot patches over POST. The framework exposes one opt-in extension (live: true) for routes that need cross-session push. The demo at demo.statorjs.dev uses three routes to show what each piece looks like in practice.

Stator isn't the first framework to take any of these positions. Where it differs is worth being plain about. So is where the other framework is the better pick.

Sharing this now, before the V1 list is built, is the point. The goal is to find out whether the paradigm is worth building toward, or whether there's a fundamental objection we haven't seen yet. The repo is open. Issues and emails are both welcome.