Foldkit 0.158.0 is out. This release focuses on Machine, Foldkit's experimental API for modeling workflows as typed transition tables.

Imagine a checkout where ClickedContinue moves Cart to Shipping, Shipping to Payment, and Payment to Review. A Machine collects those rules in one table so you can read the allowed transitions together, test them, and generate a diagram from the same definition.

Machine has been available for a while. This release makes it easier to use inside an application, and the new Machine guide covers when to reach for it, how to integrate it, and how to keep a larger flow readable. It still ships from foldkit/experimental while the API settles.

A Machine Edge now returns the same shape as update: { model }, with commands when it has work to run.

Previously, to and when took a state builder and a separate Commands callback. In this example, both callbacks build the same order:

Before:

to(
  'Placing',
  ({ state }) => CheckoutState.Placing({ order: orderFromReview(state) }),
  ({ state }) => [PlaceOrder({ order: orderFromReview(state) })],
)

After:

to('Placing', ({ state }) => {
  const nextOrder = orderFromReview(state)

  return {
    model: CheckoutState.Placing({ order: nextOrder }),
    commands: [PlaceOrder({ order: nextOrder })],
  }
})

The handler derives the order once and uses it for both the next state and the Command. The Command still executes through the Runtime after update returns.

This is a breaking change. Wrap existing state returns in { model }, and move any separate Commands callback into the same handler's commands field.

Thank you to @hdoro for suggesting that Machine Edges return Model and Commands together!

A checkout may allow cancellation from Cart, Shipping, Payment, and Review. Repeating that Edge under every state makes it harder to see which transitions actually differ.

Machine.forStates(...).on(...) now lets you declare the cancellation once in the Machine's shared array:

shared: [
  Machine.forStates(['Cart', 'Shipping', 'Payment', 'Review']).on({
    ClickedCancel: to('Cancelled', ({ state }) => ({
      model: CheckoutState.Cancelled({
        isShippingRequired: state.isShippingRequired,
      }),
    })),
  }),
]

The handler's state narrows to the selected variants, so it can read their common fields. A state-local transition overrides the shared default for the same Message. Overlapping shared declarations throw when the Machine is defined.

Shared transitions also appear in the Machine's graph analysis and Mermaid output.

Machine.fold handles the work of reading a Machine state from the enclosing Model, running a transition, writing the next state back, and returning its Commands:

const foldCheckout = Machine.fold({
  machine: checkoutMachine,
  read: (model: Model) => Option.some(model.checkout),
  write: (model, nextCheckout) => evo(model, { checkout: () => nextCheckout }),
})

Call foldCheckout(model, message) from update, or use foldCheckout(message) as a Step in Update.combine. If the Machine exists only in some Model variants, read can return Option.none() elsewhere and the fold leaves the Model unchanged.

Machines can also declare a Schema for read-only context. For example, a checkout guard can consult current inventory held elsewhere in the Model without copying it into every checkout state. Machine.fold reads that context from the enclosing Model for each transition. Direct calls to transition and step must supply it too.

Machine.step now explains why a Message produced no transition:

• OutOfAlphabet: the Message tag appears nowhere in the table.

• NotApplicable: the table knows the Message, but the current state has no Edge for it.

• GuardsFellThrough: every guard declined and there was no fallback.

• ExplicitlyIgnored: evaluation reached the new ignore() fallback.

Use ignore() at the end of a guard list when doing nothing is intentional. Tests and inspectors can distinguish that decision from guards that fell through without a fallback. Static analysis also reports Edges after ignore() as dead transitions.

If you construct or assert an Ignored result, add its required reason field. Exhaustive matches over GuardedEdge, IgnoredReason, and DeadTransitionReason also need to handle the new ignore cases.

• Machine.define accepts nested state unions without throwing at module load.

• Reachability analysis now excludes Edges shadowed by an earlier otherwise, and dead-transition reports list each Edge once.

• Machine.StateTransitions preserves state and Message narrowing when you extract a state's transition entry into a named binding.

• The docs have larger text, more space between sections, Inter for body text, and Paper Mono for code. Search is also available from the landing page.

The Machine guide walks through guards, context, shared transitions, update integration, graph analysis, and pure tests. The state machine example lets you step through a checkout and inspect its transitions as you go.

The full 0.158.0 release notes cover every package and migration detail.

Thanks to everyone building with Foldkit!

Devin

Foldkit 0.157.0 and 0.156.0 are out.

0.156.0 was a small release.

• HoverIntent now closes without the pointer grace delay when focus leaves the trigger and panel.

• Parents can programmatically close HoverIntent with HoverIntent.close, for example after a user selects a menu item.

Now for 0.157.0. The appetizer is improved type safety in Story and Scene tests. The main dish is @foldkit/oxlint-plugin updates, with a side of more ergonomic OutMessage matching.

The recommended @foldkit/oxlint-plugin preset gained two rules.

foldkit/no-impure-call-at-decision-time reports time and randomness calls made while update is deciding which Commands to return, instead of when those Commands execute.

const Save = Command.define('Save', {
  args: { createdAt: Schema.Number },
  messages: [Message.CompletedSave],
  execute: ({ createdAt }) =>
    Effect.succeed(Message.CompletedSave({ createdAt })),
})

const save = (model: Model): Update.Return<Model, Message> => ({
  model,
  // Wrong: Date.now() runs while update is deciding which Commands to return.
  commands: [Save({ createdAt: Date.now() })],
})

Move the read into the Command's Effect and return the value in its result Message:

const Save = Command.define('Save', {
  messages: [Message.CompletedSave],
  // Right: the clock is read only when the Command executes.
  execute: Clock.currentTimeMillis.pipe(
    Effect.map(createdAt => Message.CompletedSave({ createdAt })),
  ),
})

const save = (model: Model): Update.Return<Model, Message> => ({
  model,
  commands: [Save()],
})

foldkit/prefer-effect-module-names reports abbreviated and trailing-underscore Effect import aliases, and auto-fixes aliases when it can identify the exported module name.

Existing applications using the preset may produce new lint errors after upgrading.

Across the preset, rules now recognize aliases for Foldkit, @foldkit/ui, Effect, and child Message imports. They ignore local shadows and no longer mistake unrelated message fields for Submodel Messages.

The preset already reported parent code that constructs a child Message. In 0.157.0, the rule also catches that code when the child import is aliased. For example, a parent should not decide that opening a Dialog means dispatching its RequestedOpen Message:

const foldDialogOpen = Update.foldChildStep({
  // Wrong: the parent constructs one of Dialog's internal Messages.
  update: (dialog: Dialog.Model) =>
    Dialog.update(dialog, Dialog.Message.RequestedOpen()),
  read: readDialog,
  write: writeDialog,
  toParentMessage: toGotDialogMessage,
  foldOutMessage: foldDialogOutMessage,
})

Dialog exposes open, so the parent can fold that operation without reaching into the child's Messages. Parents should drive child behavior through update functions exposed by the child:

const foldDialogOpen = Update.foldChildStep({
  // Right: the parent calls an update function owned by Dialog.
  update: Dialog.open,
  read: readDialog,
  write: writeDialog,
  toParentMessage: toGotDialogMessage,
  foldOutMessage: foldDialogOutMessage,
})

This lets the parent call a child-owned update function without depending on the child's internal Messages. Update.foldChildStep still handles the child Model, Commands, and OutMessages. Animation in @foldkit/ui now exposes show, hide, and toggle update functions for the same reason.

Foldkit union matchers now accept a structurally refined union as their optional second type argument. For a Listbox whose value is refined to Plan, this lets Listbox.OutMessage.match keep value typed as Plan without a separate Effect Match pipeline.

Before:

// Before: preserving Plan requires a separate Effect Match pipeline.
const foldListboxOutMessage = Match.type<Listbox.OutMessage<Plan>>().pipe(
  Match.withReturnType<Update.Step<Model, Message>>(),
  Match.tagsExhaustive({
    Selected:
      ({ value }) =>
      model => ({ model: evo(model, { maybePlan: () => Option.some(value) }) }),
  }),
)

After:

// After: Foldkit's matcher preserves Plan directly.
const foldListboxOutMessage = Listbox.OutMessage.match<
  Update.Step<Model, Message>,
  Listbox.OutMessage<Plan>
>({
  Selected:
    ({ value }) =>
    model => ({ model: evo(model, { maybePlan: () => Option.some(value) }) }),
})

The new form is shorter, remains exhaustive, and keeps value typed as Plan in the Selected handler.

Other changes:

• Story and Scene now type-check Message and OutMessage steps against the update under test, with a new Story.steps API for reusable Story sequences.

• Mounts can use the new viewStateChanges Stream to stop DOM interaction while DevTools shows a historical view.

• Textarea content must now use h.Value.

• Machine.unreachableStates and Machine.deadTransitions can now account for states entered through persistence or deep links.

• Dialog now falls back to the first focusable element—or the dialog itself—when its requested focus target is missing or cannot receive focus.

• DevTools overlay dependencies are now preloaded, so Vite does not reload on first use.

• The former Manifesto page is now Why Foldkit.

Thank you to @rjdellecese for proposing the Effect module naming convention and Mount view-state API, and to @artile for reporting the Dialog focus issue. Thank you also to @armancharan for adding vitest.config.ts typechecking across the repo and @filipfalcon for the Vite preload fix!

The full 0.156.0 and 0.157.0 release notes cover every package and migration detail.

Thanks to everyone building with Foldkit!

Devin

Foldkit 0.155.0 is out. I never announced 0.154.0, so this post covers both.

0.154.0 shipped earlier this week with several additions worth calling out:

• h.OnClick gained defaultAction, propagation, and focusSelector controls. Foldkit applies them synchronously before dispatching the Message, covering browser behavior such as preventing a default action, stopping DOM propagation, and focusing an existing element inside the originating gesture. h.OnClickFocus was deprecated in 0.154.0 and is removed in 0.155.0. Thank you to @hdoro for pointing out the limitation in h.OnClick!

• h.OnFocusEnter and h.OnFocusLeave model focus across a compound region. Put them on a common ancestor and Foldkit dispatches only when focus crosses that boundary, not when it moves between descendants.

• Update.foldChild and Update.foldChildStep can now emit a derived parent OutMessage from foldOutMessage. A child fact can update the current Submodel and produce a different fact for its parent without making the parent Message handler inspect the child Message again.

• Popover now supplies a headless arrow attribute bundle and keeps it positioned as the panel flips and shifts. You draw the arrow; Foldkit publishes the placement and offsets. Thank you to @wmaurer for contributing it!

• @foldkit/oxlint-plugin gained foldkit/no-empty-to-parent-out-message, which catches toParentOutMessage mappers that always return undefined and should be omitted.

Now for 0.155.0.

Foldkit gained server rendering two weeks ago. It worked, but building a server-rendered application still happened across three commands: build the browser bundle, build the server bundle, then prerender the configured routes.

That separation mattered as soon as another Vite plugin needed to participate in the build. A deployment adapter or host plugin could join the browser build and never see the server build that followed in a separate process. It could deploy half an application. The browser and server builds could also mint different build ids, producing HTML that hydration correctly refused.

@foldkit/vite-plugin 0.20.0 now owns the whole build:

foldkit({
  buildId,
  ssr: {
    serverEntry: '/src/entry.server.ts',
    build: { prerender: true },
  },
})

Run vite build once. Vite produces the browser bundle, the server bundle, and, when prerender is enabled, a page for every path exported by the server entry. Every environment belongs to the same build and shares the same build id.

The build also writes foldkit.build.json beside the server bundle. It records the output directories, server entry, and generated paths so a deployment host can derive its routing behavior from the artifact instead of asking you to repeat it in platform settings.

Applications without ssr.build still produce a browser bundle exactly as before.

This work came from @filipfalcon. Thank you!

Mount.define and Mount.defineStream used to take positional inputs, then accept their work in a second call. A Mount with args had a curried args => element => Effect<Message> body.

It looked compact, but it hid a bad boundary: the outer function ran when view constructed the MountAction. Anything written between those arrows ran during a pure view, on every render, rather than when the element entered the DOM.

Mount definitions now use one config object with named args, messages, and execute fields:

Before:

const AnchorPopover = Mount.define(
  'AnchorPopover',
  { buttonId: Schema.String, anchor: AnchorConfig },
  CompletedAnchorPopover,
)(
  ({ buttonId, anchor }) =>
    element =>
      Effect.gen(function* () {
        // ...
      }),
)

After:

const AnchorPopover = Mount.define('AnchorPopover', {
  args: { buttonId: Schema.String, anchor: AnchorConfig },
  messages: [CompletedAnchorPopover],
  execute: ({ element, buttonId, anchor }) =>
    Effect.gen(function* () {
      // ...
    }),
})

execute has the same flat shape with or without args. Constructing a MountAction now runs nothing. The runtime calls execute only after the element exists.

This is a breaking change, and @foldkit/ui 0.155.0 now requires foldkit 0.155.0 because its Mount definitions use the new shape. The Mount docs have the complete migration.

Thank you to @hdoro for suggesting this API change!

@foldkit/ui now includes HoverIntent, a headless Submodel for interactions that reveal a panel from a trigger.

It opens after a configurable pointer delay, stays open while the pointer or focus moves between the trigger and panel, and closes after a configurable grace period. Focus opens immediately. Escape closes immediately and prevents reopening until the pointer and focus have both left.

HoverIntent returns trigger and panel event bundles. It does not create markup, choose ARIA roles, position the panel, or style anything. A Hover Card can pair it with Anchor. A hover menu can use it to keep its items available as the pointer moves from the trigger into the panel.

The HoverIntent docs have current examples and API details.

Thank you to @SyahrulBhudiF for contributing it!

There is plenty more in 0.155.0:

• FieldValidation.match exhaustively matches NotValidated, Validating, Valid, and Invalid field states without a manual Effect Match pipeline.

• CustomElement builders now accept ChildAttribute alongside ordinary attributes, so published Submodel attribute groups compose with them just like native HTML element builders. Thank you to @jay-zahiri for noting this issue!

• Scene preserves every OutMessage emitted by one update-producing step in runtime order. Use expectOutMessages when a batch produces several.

• The renderer does less work in its hot path by caching unchanged document metadata, writing ordinary properties directly, and skipping module scans when a VNode has no module data.

• Dialog now releases its resources when ShowDialog fails or is interrupted, and when CloseDialog finds that the element is already gone. Thank you to @wmaurer for the fixes!

• ManagedResource now clears its reference and dispatches its release Message when the user-provided release effect fails.

• The deprecated h.OnClickFocus is gone. Use h.OnClick(message, { focusSelector }).

The packages now build and test with TypeScript 7 as well. The full 0.154.0 and 0.155.0 release notes cover every package and migration detail.

Thanks to everyone building with Foldkit!

Devin

Until today, Foldkit was purely an SPA framework. The server sent an HTML file to the client, the client requested the JavaScript bundle, and once it loaded, the application booted.

There are issues with this approach in isolation:

• The user sees the server's HTML before the JavaScript loads. Unless you prerender HTML that matches the loaded app, that is typically a blank page.

• There is no first-class way to do SSG. The workaround is a heavy prerender step: for example, using Playwright to visit each route and capture HTML (which the Foldkit website used to do).

• There is no first-class way to do request-time SSR: for example, the server sending the client an initial HTML file personalized to the logged-in user.

There was one more problem. Foldkit not having SSR was the deal-breaker for Michael Arnaldi, BDFL of Effect. And that simply will not do.

So, Foldkit can render on the server now. It shipped today under foldkit/experimental/server. It will be promoted to foldkit/server once the community puts it through its paces.

foldkit/experimental/server ships renderToString, and foldkit/runtime ships hydrate. Together, they give a Foldkit application two new ways to reach the browser: generate static HTML for selected routes during the build, or render each request on a server. When the server and client agree, the browser adopts the served HTML in place. A mismatched subtree is rebuilt, and an invalid or cross-deployment handoff is refused. The application that boots is the same Foldkit application you wrote yesterday.

A Foldkit app can remain a pure client-side SPA. Server rendering is opt-in.

SSG and SSR are the same thing run at different times. Either a build script calls your server entry once per URL and writes files, or a server calls it once per request and sends the response. The entry is a small module that derives flags from a Request and asks Foldkit to render:

import { Effect } from 'effect'
import { Server } from 'foldkit/experimental'

import { readCountCookie } from './cookie'
import { Flags, init, view } from './main'

const flagsForRequest = (request: Request): Flags => ({
  initialCount: readCountCookie(request.headers.get('cookie') ?? ''),
})

export const renderPage = (request: Request): Promise<Server.EntryResult> =>
  Effect.runPromise(
    Effect.gen(function* () {
      const renderedApplication = yield* Server.renderToString(
        { Flags, init, view },
        {
          flags: flagsForRequest(request),
          buildId: import.meta.env.FOLDKIT_BUILD_ID,
        },
      )

      return Server.Rendered(renderedApplication, {
        headers: {
          'cache-control': 'private, no-store',
          vary: 'cookie',
        },
      })
    }),
  )

The Flags Schema, init, view, and flagsForRequest are provided by you. The rest is wiring.

The same entry serves Vite in development, a Node host in production, a build script for static generation, and fetch-native runtimes like Cloudflare Workers. Hosts are interchangeable because the entry deals only in Web standards: a Web Request goes in, and the host turns the result into a Web Response.

Foldkit's view is a pure function of the Model, so most of server rendering was less "add SSR to the framework" and more "call the same function somewhere else."

If you are using Foldkit without SSR, the browser runs the whole sequence: your flags Effect produces the flags, init turns them into the first Model, and view renders it.

With SSR, the server runs the front of that sequence and the browser finishes it:

• On the server, flagsForRequest turns the request into flags, init builds the first Model, and view renders it to HTML. That HTML ships to the browser with the flags serialized alongside it.

• On the client, init runs again with those same flags, rebuilds the initial Model, and view renders it. Hydration adopts matching server DOM and rebuilds a mismatched subtree from its nearest parent.

There is no separate server-side Model to reconcile with the client's. Both sides derive the initial Model from the same flags and init, then render it through the same view.

After hydration, the initial Commands run, and your Foldkit application behaves like a typical SPA with client-side navigation.

Check out the new docs page on Server Rendering, and the runnable Static Site Generation and Server-Side Rendering examples.

This website (foldkit.dev) now prerenders every route through the same renderPage contract (SSG). The page you are reading hydrated in place.

Foldkit is not getting a second programming model. It is gaining a crucial capability.

There are no server components, no 'use client' or 'use server' boundaries, and no plan for them: the view is one function of one Model. Server rendering changes where the first paint comes from, not how you write applications.

Scaffold a Foldkit SSR application:

npx create-foldkit-app@latest --rendering ssr

Check it out and let me know what breaks. And don't be a stranger!

Devin

Beep. Beep. Beep.

APS-4 is on the fritz again.

Time to twiddle my thumbs.

Can you really blame me?

I’ve done the math. My job is oversight. Manual manipulation results in glutamate accumulation. Oversight quality suffers. The mission suffers. Therefore, I don’t do manual. QED.

Besides, I don’t pine for the good old days.

APS-4 does the wrong thing sometimes. It doesn’t matter.

Mostly, it does what I want. It does what I don’t know I want.

Every outage I realize how little I ever knew.

Beep. Beep. Beep.

Good time to check telemetry.

Day 417. 1,546 logs transmitted. 184 supply drops. 775 commendations. 9,341 recent supply requisitions. Progress unknown. Mission ambiguous. I don’t know what these numbers mean.

I feel itchy. There’s work to be done. Reports don’t cease when lunar base servers go down.

But I’m past the point of commanding this thing with my own two hands. Not in this asteroid field.

APS-4 has 10,000 hands. Each hand has 10,000 fingers. Even its fingers have fingers.

I’m not proud enough to cosplay as a billion fingers.

Beep. Beep. Beep.

I do miss driving stick. I was a decent pilot.

Sometimes, when the radar is clear, I kill the uplink, just to remember what it was like. I probably hand-grind my coffee for the same reason.

At least they haven’t made autopilot autopilot yet.

Beep. Beep. Beep.

I converse with APS-4 more than I would like. It is effective and exhausting.

I receive daily transmissions from fellow astronauts. I can make out their ships in the distance. Their messages are wonderful. They are so human.

In these quiet moments, I wonder if—

We sincerely apologize for the disruption to your service. APS-4 access is restored. State your request.

APS-4, dispatch mission log.