) }) ``` The React cell is a memoized component. Its callbacks close over `x`, `y`, and `dispatch`, and their dependency arrays keep those values current. React Compiler can produce equivalent memoization without the handwritten wrappers when enabled. ## Guarantees React Cannot Provide Within a Foldkit application, the framework enforces several properties that React leaves to the selected state and effect architecture. A React application can recreate some of them with a reducer, store, event system, or additional tooling, but React itself does not require them. ### The Message union as total input domain The parent Message union is the total input domain of parent update. A child Submodel repeats that property behind its `Got*Message` wrapper. Every Runtime-driven Model transition therefore enters through a typed value from one of those unions. React’s Action union provides the same property for this reducer. It does not cover state internal to Headless UI or work begun directly in handlers and Effects, because those paths do not use the reducer. ### Safe evolution under type pressure Both versions can exhaustively handle a new union variant in their transition function. Foldkit extends that check across the Runtime channel because every parent state transition uses a Message. Adding a Message makes `Message.match` fail until update handles it. Exhaustiveness catches an omitted branch, not an incorrect branch or a forgotten product requirement. Tests still have to establish what the new case should do. ### Side effects as assertable values A Command has a name, arguments, result Messages, and identity in DevTools and tests. Story and Scene can assert that update returned it before choosing a result. React Effects and handlers are executable code rather than returned descriptions, so their tests observe execution or inject an application-specific abstraction. ### Time-travel that covers UI internals Foldkit DevTools records Messages and Model snapshots. Because Foldkit UI Submodels live in the Model, their interaction state participates in that history. React DevTools inspects component state, and reducer-oriented tools can add action history for application state. Headless UI’s internal Hook state is not part of the pixel editor reducer, so it does not appear in a reducer replay. ### Tests share the runtime’s pipeline Story calls update with Messages and handles the Commands update returns. Scene adds the actual Foldkit view and event attributes. The same values cross those boundaries in production and tests. The React tests also exercise production reducers and components. Their extra jsdom and mocking requirements come from the browser and Hook boundaries selected by this implementation, not from an inability to test React code. ### One place to look when the Model is wrong After init, Foldkit’s application Model is replaced only by update. A wrong Model transition therefore comes from an update handler or a helper it calls. Command and Subscription code can produce the wrong Message, but it cannot mutate the Model around update. This React application gives its reducer state the same central transition point. Debugging can also cross the reducer boundary when an Effect dispatches the wrong Action or a Headless UI interaction concerns state outside the reducer. ### No stale closures in view, update, or Subscriptions Foldkit update receives the current Model with each Message, and Subscription lifetimes are rebuilt from declared Model dependencies. The framework does not use Hook dependency arrays for either boundary. Closures still exist in application code, and [Mount](https://foldkit.dev/core/mount) arguments are intentionally captured when an element mounts. Commands also capture the arguments supplied when update creates them. Foldkit narrows where captured values matter; it does not remove JavaScript closures. ## Which Scales Better? The pixel editor shows the structures each codebase will extend. Future features would still involve design choices on both sides. ### Remote persistence In Foldkit, `ReleasedMouse` could return a `SyncCanvas` Command alongside `SaveCanvas`. In React, the application could extend the persistence Hook, add another Effect, or move synchronization behind an event-driven service. Request ordering, retries, and cancellation need explicit policy in either implementation. Foldkit keeps the decision to start a Command beside the Model transition. React lets the application choose whether that decision belongs in a handler, Effect, middleware, or data library. ### Multiplayer editing A multiplayer feature should define a wire protocol rather than send the entire UI Model. Foldkit can validate remote Messages or domain events with Schema and route accepted values through update. Local UI Submodels can remain local. The React version can validate the same protocol and dispatch reducer Actions for accepted events. Foldkit supplies the single Message pipeline as a framework constraint; React requires the application to choose and maintain that boundary. ### Animation timeline Both versions would add frames, a current index, and playback state. Foldkit can model playback as a Subscription that emits `AdvancedFrame`. React can model it with an Effect and `useEffectEvent`, which reads the current frame data without restarting the interval unless a synchronization dependency changes. The difference remains placement. Foldkit sends each tick through update. React synchronizes the timer from component state and dispatches Actions from its callback. ### Persistent undo history Foldkit can persist undo history with a Command and restore it through init or an initialization Command. The React version can extend `useLocalStorage` or add an IndexedDB Hook and initialize reducer state from the stored value. Both versions need versioning, decoding, and failure behavior for stored data. Foldkit’s Schema and Command result Messages provide built-in places for those concerns; React can use the validation and effect libraries the application selects. Both applications can grow to support these features. The difference is whether each feature has to join an existing pipeline. Foldkit grows through the same named categories: Model fields, Messages, update handlers, Commands, Subscriptions, and Submodels. React grows through components, Hooks, reducer Actions, and any additional state or effect libraries the team chooses. Foldkit’s constraint keeps paying the same dividend: a new behavior has a defined home and joins the same timeline. React preserves more freedom to choose that home, which is valuable until those choices become coordination work. ## Conclusion The pixel editor makes the trade concrete. React keeps rendering and lifecycle close to components and can adopt an enormous ecosystem around them. Its reducer provides a strong state core, while handlers, custom Hooks, and Headless UI complete the application around that core. Foldkit puts the application Model, state transitions, and event-driven Commands behind one Runtime channel. Subscriptions and Submodels follow the same typed-data approach, and Story, Scene, and DevTools operate on those values directly. Choose React when its ecosystem and freedom to select an application architecture matter more than having one imposed by the framework. Choose Foldkit when you want the framework to enforce where state transitions, effects, and lifecycles belong instead of relying on each application to establish those boundaries. That constraint is not something Foldkit asks you to tolerate. It is what the framework is for. --- Source: https://foldkit.dev/react/foldkit-vs-react-effect-atom Section: Guides # Foldkit vs React + Effect Atom ## Overview This page is for people who have already chosen Effect. In Effect 4, [Effect Atom](https://github.com/Effect-TS/effect/tree/main/packages/atom) provides reactive state primitives through `effect/unstable/reactivity`, with view bindings such as `@effect/atom-react`, `@effect/atom-solid`, and `@effect/atom-vue`. The host framework still owns rendering and components. Foldkit owns the application runtime and view layer. It renders through a virtual DOM built on [Snabbdom](https://github.com/snabbdom/snabbdom), and it includes routing, UI components, DevTools, and Story and Scene testing. Its architecture has one Model, a Message union, and an update function. Side effects return to the runtime as Commands and other lifecycle primitives. The choice is therefore larger than where to store state. React with Effect Atom is a React application with a reactive Effect state layer. A Foldkit application uses a different runtime, view model, and testing model. They are different paradigms that happen to share Effect. Related page This page assumes you are already using Effect. If you are coming from plain React, [Foldkit vs React](https://foldkit.dev/react/foldkit-vs-react-side-by-side) covers the broader architectural differences. ## What They Share Both approaches can use Effect values, typed errors, Layers, structured concurrency, and Schema validation at application boundaries. In Effect Atom, an Effect can run inside an async atom or a function atom. In Foldkit, a Command wraps an Effect and returns its result as a Message. Above that Effect foundation, their responsibilities differ. Effect Atom provides state and reactivity to a host view framework. Foldkit owns the runtime, rendering, routing, lifecycle primitives, and testing tools. ## Many Atoms vs One Model An atom is a reactive container for a value. You can create state with `Atom.make`, derive an atom from other atoms, read it with `useAtomValue`, and write it with `useAtomSet`. The registry tracks dependencies and notifies the components that read a changed atom. State is distributed by design, and that is the point. A feature can own its atoms, and a component can update any writable atom it imports. The cost of that locality is that no single value represents the state of the application and no single type lists every way it can change. Foldkit centralizes state in the [Model](https://foldkit.dev/core/model). The [Message](https://foldkit.dev/core/messages) union lists the facts the application handles, and [update](https://foldkit.dev/core/update) defines how those facts change the Model. Those are framework constraints, not conventions a team maintains by discipline. [Submodels](https://foldkit.dev/core/submodel) split a large application into smaller state machines while preserving the same parent-to-child Message flow. ## How State Changes The state models become concrete when a user adds or edits a todo. ### Effect Atom: setters at the call site A React component obtains a setter with `useAtomSet`. The setter can receive an updater closure: ``` import { Atom } from 'effect/unstable/reactivity' import { useAtomSet, useAtomValue } from '@effect/atom-react' type Filter = 'All' | 'Active' | 'Done' // State is a set of independent reactive cells. const filterAtom = Atom.make('All').pipe(Atom.keepAlive) const todosAtom = Atom.make>([]).pipe(Atom.keepAlive) // Any component can write any atom, with an inline updater closure. const AddTodoButton = () => { const setTodos = useAtomSet(todosAtom) return ( ) } const ClearDoneButton = () => { const setTodos = useAtomSet(todosAtom) return ( ) } const FilterTabs = () => { const filter = useAtomValue(filterAtom) const setFilter = useAtomSet(filterAtom) // ... each transition is an anonymous closure, scattered across components } ``` In this example, the ways `todosAtom` changes live at its setter call sites. An atom application can instead expose named write functions or writable derived atoms. That centralization is an application convention. Foldkit requires every Model transition to pass through update. ### Foldkit: one Message union, one update The Foldkit version represents the same actions as Messages: ``` import { Array, Schema as S } from 'effect' import { type Update } from 'foldkit' import { defineMessageUnion } from 'foldkit/message' // MODEL const Filter = S.Literals(['All', 'Active', 'Done']) export const Model = S.Struct({ todos: S.Array(Todo), filter: Filter, }) type Model = typeof Model.Type // MESSAGE const Message = defineMessageUnion({ AddedTodo: {}, ClearedDoneTodos: {}, SelectedFilter: { filter: Filter }, }) type Message = typeof Message.Type // UPDATE export const update = (model: Model, message: Message) => Message.match>(message, { AddedTodo: () => ({ model: evo(model, { todos: Array.append(emptyTodo()) }), }), ClearedDoneTodos: () => ({ model: evo(model, { todos: Array.filter(todo => !todo.done) }), }), SelectedFilter: ({ filter }) => ({ model: evo(model, { filter: () => filter }), }), }) ``` `AddedTodo`, `ClearedDoneTodos`, and `SelectedFilter` appear in DevTools and in Story or Scene tests. “How can the todo list change?” is answered by one Message union and one update function. `Message.match` reports every place that must handle a newly added Message variant. ## Async State Both provide a value type for in-progress Effect results, but the value lives in a different place. ### Effect Atom: AsyncResult `Atom.make` accepts an Effect directly. When the Effect needs Layer-provided services, `Atom.runtime` creates an atom runtime and `runtime.atom` runs the Effect with that context. The resulting atom contains an `AsyncResult`: `Initial`, `Success`, or `Failure`, with a `waiting` flag for refreshes. `AsyncResult.builder` renders those cases. ``` import { Cause, Effect } from 'effect' import { AsyncResult, Atom } from 'effect/unstable/reactivity' import { useAtomValue } from '@effect/atom-react' const runtime = Atom.runtime(Api.Default) // An async atom evaluates an Effect and exposes an AsyncResult. const userAtom = runtime.atom( Effect.gen(function* () { const api = yield* Api return yield* api.getUser() }), ) const UserCard = () => { const user = useAtomValue(userAtom) return AsyncResult.builder(user) .onInitial(() => ) .onFailure(cause => ) .onSuccess(user => ) .render() } ``` The Effect runs when the registry first evaluates the atom, and the registry stores the result and tracks dependencies. `Atom.family` creates keyed atoms. `Atom.swr` adds stale-time and revalidation behavior, while `AtomHttpApi` and `AtomRpc` integrate Effect clients. React bindings also provide Suspense hooks. ### Foldkit: remote state in the Model Foldkit stores remote state in the Model. [AsyncData](https://foldkit.dev/core/async-data) represents six states: `Idle`, `Loading`, `Refreshing`, `Failure`, `Stale`, and `Success`. A Command performs the request, and its result returns through update as a Message. ``` import { Effect, Schema as S } from 'effect' import { AsyncData, Command, type Update } from 'foldkit' import { defineMessageUnion } from 'foldkit/message' import { Api } from './api' // MODEL // Remote state is a value in the Model. AsyncData is the shipped six-state // union, so there is no hand-rolled loading/failure/stale union to maintain. const UserAsyncData = AsyncData.Schema(User, ApiError) export const Model = S.Struct({ user: UserAsyncData.schema, }) type Model = typeof Model.Type // MESSAGE const Message = defineMessageUnion({ ClickedLoadUser: {}, SucceededLoadUser: { user: User }, FailedLoadUser: { error: ApiError }, }) type Message = typeof Message.Type // COMMAND // Api is an Effect service; Api.Default is its layer. const FetchUser = Command.define('FetchUser', { messages: [Message.SucceededLoadUser, Message.FailedLoadUser], execute: Effect.gen(function* () { const api = yield* Api const user = yield* api.getUser() return Message.SucceededLoadUser({ user }) }).pipe( Effect.catch(error => Effect.succeed(Message.FailedLoadUser({ error }))), Effect.provide(Api.Default), ), }) // UPDATE export const update = (model: Model, message: Message) => Message.match>(message, { ClickedLoadUser: () => ({ model: evo(model, { user: () => UserAsyncData.Loading() }), commands: [FetchUser()], }), SucceededLoadUser: ({ user }) => ({ model: evo(model, { user: () => UserAsyncData.Success({ data: user }) }), }), FailedLoadUser: ({ error }) => ({ model: evo(model, { user: () => UserAsyncData.Failure({ error }) }), }), }) ``` `AsyncData` includes stale-while-revalidate and keep-stale-on-failure states. It does not provide a fetching registry or choose refresh policy. The application models a cache in the Model and decides when to run each Command. Remote data then shares the same Message timeline and tests as the rest of the Model. Effect Atom gives you more data-fetching machinery out of the box. Foldkit gives remote state no separate architectural lane. That distinction matters when remote data starts interacting with the rest of the application. ## Side Effects and Lifecycle Both can express side effects as Effect values. They differ in how an effect is connected to application state and lifetime. ### Effect Atom: effects live inside atoms `runtime.fn` creates a callable atom for a mutation. Its `reactivityKeys` can refresh atoms that subscribe to matching keys. An atom can also acquire a listener and register its cleanup with `addFinalizer`; `useAtomMount` keeps that atom mounted for the component’s lifetime. ``` import { Effect } from 'effect' import { Atom } from 'effect/unstable/reactivity' import { useAtomMount, useAtomSet } from '@effect/atom-react' // A mutation is a function atom. Reactivity keys invalidate dependents. const createTodoAtom = runtime.fn( Effect.fnUntraced(function* (text: string) { const api = yield* Api yield* api.createTodo(text) }), { reactivityKeys: ['todos'] }, ) // A global listener is an atom that wires addEventListener in its body, // then tears it down with a finalizer. const mouseUpAtom = Atom.make(get => { const onUp = () => get.setSelf(false) window.addEventListener('mouseup', onUp) get.addFinalizer(() => window.removeEventListener('mouseup', onUp)) return false }) const Canvas = () => { useAtomMount(mouseUpAtom) // keep the listener alive while this component is mounted const createTodo = useAtomSet(createTodoAtom) // ... } ``` Effects remain colocated with the atoms that perform them. Dependencies between a mutation and refreshed atoms can be declared through reactivity keys, which are runtime values rather than a TypeScript union checked for exhaustiveness. ### Foldkit: Commands and Subscriptions Foldkit selects a lifecycle primitive based on what causes the work. A [Command](https://foldkit.dev/core/commands) runs after a Message. A [Subscription](https://foldkit.dev/core/subscriptions) runs while a Model condition holds. A [Mount](https://foldkit.dev/core/mount) follows an element’s lifetime, and a [ManagedResource](https://foldkit.dev/core/managed-resources) follows Model state while exposing a stateful handle to Commands. ``` import { Effect, Schema as S, Stream } from 'effect' import { Command, Subscription } from 'foldkit' import { Api } from './api' // A side effect is a Command returned from update. It has a name, shows up // in DevTools next to the Message that produced it, and is assertable in // tests. Api is an Effect service; Api.Default is its layer. const CreateTodo = Command.define('CreateTodo', { args: { text: S.String }, messages: [SucceededCreateTodo, FailedCreateTodo], execute: ({ text }) => Effect.gen(function* () { const api = yield* Api yield* api.createTodo(text) return SucceededCreateTodo() }).pipe( Effect.provide(Api.Default), Effect.catch(() => Effect.succeed(FailedCreateTodo())), ), }) // Here the global listener becomes a Subscription: an external event source // bound to a slice of the Model. The runtime subscribes and unsubscribes as // model.isDrawing changes. No addEventListener, no cleanup, no stale closure. export const subscriptions = Subscription.make()(entry => ({ mouseRelease: entry( { isDrawing: S.Boolean }, { modelToDependencies: model => ({ isDrawing: model.isDrawing }), dependenciesToStream: ({ isDrawing }) => Stream.when( Subscription.fromEvent({ target: document, type: 'mouseup', toMessage: () => ReleasedMouse(), }), Effect.sync(() => isDrawing), ), }, ), })) ``` The difference is locational. Effect Atom colocates effects with atoms, and any atom may run one. Foldkit assigns effects to a small set of lifecycle primitives based on what causes them. The `mouseRelease` Subscription starts and stops from Model state, then emits Messages so the resulting change still passes through update. ## The View Layer Is Still React Effect Atom changes the state layer, not React’s rendering rules. Components still use hooks, closures, and React’s memoization tools. ### Effect Atom plus React This version stores the todos in one array atom. It uses `memo` and `useCallback` to avoid rendering an unchanged row when the array changes: ``` import { memo, useCallback } from 'react' import { useAtomSet } from '@effect/atom-react' // The view layer is still React: memo to skip re-renders, useCallback to keep // the handler reference stable, a dependency array you have to get right. const TodoItem = memo(({ todo }: { todo: Todo }) => { const setTodos = useAtomSet(todosAtom) const toggle = useCallback( () => setTodos(todos => todos.map(candidate => candidate.id === todo.id ? { ...candidate, done: !candidate.done } : candidate, ), ), [setTodos, todo.id], ) return (

{todo.text}

) }) ``` Those optimizations are not required for correctness. A per-item atom could also give each row a narrower subscription. Either design still follows React’s hook and closure rules, and React Compiler can automate some memoization when the component satisfies its constraints. ### Foldkit The Foldkit item is a function that returns virtual DOM data. Its event handler dispatches a Message value: ``` import type { Html, HtmlBuilder } from 'foldkit/html' // The view is a plain function returning data. No memo, no useCallback, no // dependency array. The event is a Message value, not a closure, so there is // nothing to stabilize at the boundary. const todoItem = (todo: Todo, h: HtmlBuilder): Html => h.li( [], [ h.input([ h.Type('checkbox'), h.Checked(todo.done), h.OnClick(ClickedTodo({ id: todo.id })), ]), todo.text, ], ) ``` There is no component Hook state, dependency array, or callback identity to stabilize. When a view subtree is expensive, [view memoization](https://foldkit.dev/core/view-memoization) skips it based on Model-derived inputs. ## One Timeline vs Many Cells Every Foldkit state change is a Message processed by update. Foldkit DevTools records those Messages and the resulting Models, so it can replay the application timeline. This site runs on Foldkit; the DEV button in the bottom-right corner opens its DevTools. Effect Atom’s registry holds the current value of many cells and updates their dependents. It does not define one app-wide union of named events, so there is no equivalent built-in Message timeline to replay. An application can add its own event model or logging when that history is useful. ## Testing Foldkit’s update function is pure: given a Model and a Message, it returns the next Model and Commands. That shape supports two [testing](https://foldkit.dev/testing) tools. [Story](https://foldkit.dev/testing/story) sends Messages through update, inspects the Model, and resolves Commands by supplying their result Messages. The test can assert that a Command was returned without executing its Effect. ``` import { AsyncData } from 'foldkit' import { Command, given, message, model, story } from 'foldkit/story' import { expect, test } from 'vitest' test('loading a user: the Command fires, resolves, the Model lands on Success', () => { story( update, given({ user: AsyncData.Idle() }), message(ClickedLoadUser()), Command.expectExact(FetchUser), Command.resolve(FetchUser, SucceededLoadUser({ user: ada })), model(model => { expect(model.user).toStrictEqual(AsyncData.Success({ data: ada })) }), ) }) ``` [Scene](https://foldkit.dev/testing/scene) renders the view, finds elements by accessible role or text, dispatches events through update, and resolves Commands inline. ``` import { Command, click, expect, given, inside, role, scene, text, } from 'foldkit/scene' import { test } from 'vitest' test('click load, resolve the fetch, see the profile', () => { scene( { update, view }, given(model), click(role('button', { name: 'Load user' })), expect(text('Loading…')).toExist(), Command.expectExact(FetchUser), Command.resolve(FetchUser, SucceededLoadUser({ user: ada })), inside(role('article'), expect(text('Ada Lovelace')).toExist()), ) }) ``` An Effect Atom application uses the testing tools of its host framework. In React, a user-facing test commonly renders a component with React Testing Library and jsdom, then waits for the atom’s Effect and React render to finish: ``` import { expect, test, vi } from 'vitest' import { render, screen } from '@testing-library/react' import userEvent from '@testing-library/user-event' test('loading a user renders the profile', async () => { // userAtom runs an Effect that fetches the user, so the test stubs the // network boundary and renders the component tree in jsdom. vi.spyOn(globalThis, 'fetch').mockResolvedValue( Response.json({ name: 'Ada Lovelace' }), ) render() await userEvent.click(screen.getByRole('button', { name: /load user/i })) expect(screen.getByText('Loading…')).toBeInTheDocument() // The atom resolves asynchronously, so findByText has to poll until the // AsyncResult transitions to Success and React re-renders. expect(await screen.findByText('Ada Lovelace')).toBeInTheDocument() }) ``` Atom Effects can also be tested below the component boundary. The architectural difference is that Foldkit exposes Commands as returned values. The Story can name the requested effect without running it, while the React component test observes the Effect through the atom and rendered interface. ## Scaling Complexity An Effect Atom application grows a graph of atoms. Adding an independent atom is local, derived atoms declare their dependencies, and fine-grained subscriptions limit which components update. Understanding a cross-feature change may require following atom reads, writes, and reactivity keys across files. A Foldkit application grows its Model, Message union, and update logic. Exhaustive matching keeps the transition catalog complete, but a large update function eventually needs to be divided into [Submodels](https://foldkit.dev/core/submodel). Submodel composition adds explicit parent-child wiring. The trade-off is locality versus a central index. Effect Atom favors independently composable reactive cells. Foldkit favors an explicit state machine whose transitions share one runtime path. ## AI-Assisted Development Foldkit’s closed Message unions and exhaustive updates give a coding agent a bounded list of state transitions and compile errors when a new variant is unhandled. The type system turns a new Message into a concrete to-do list. Commands, Subscriptions, and views also have distinct roles, which narrows where related code should live. Effect Atom favors feature-local atoms, so an agent instead follows imports, derived dependencies, setters, and reactivity keys. That can make a local feature compact while requiring more repository search for changes that cross several atoms. Foldkit’s [AI tools](https://foldkit.dev/ai/overview) document its framework-specific patterns for agents that do not already know them. ## Practical Trade-offs Architecture aside, several practical factors affect the choice. React + Effect Atom Foldkit Ecosystem React components, tooling, and libraries [Foldkit UI](https://foldkit.dev/ui/overview) , plus [Mount](https://foldkit.dev/core/mount) and [CustomElement](https://foldkit.dev/core/custom-element) for third-party integration Incremental adoption Add atoms to an existing React application Owns the application runtime, though [Embedding](https://foldkit.dev/core/embedding) can mount it inside another page Data fetching `AsyncResult` , SWR, Suspense, families, and Effect HTTP/RPC integration [AsyncData](https://foldkit.dev/core/async-data) for state, with fetching, caching, and refresh policy modeled through the Model and Commands Fine-grained reactivity Components subscribe to the atoms they read Top-down view evaluation with virtual DOM diffing and [view memoization](https://foldkit.dev/core/view-memoization) View model React components and JSX Typed view functions and an HTML builder DSL ## Conclusion They share Effect. Above that foundation, they choose different application architectures. Choose React with Effect Atom when you want Effect-native reactive state inside React, incremental adoption, fine-grained subscriptions, and its async atom tools. Choose Foldkit when you want the Elm Architecture to govern the whole application, including rendering, lifecycle, DevTools, and tests. Effect Atom composes a graph of reactive cells inside a host framework. Foldkit gives the application one state machine and makes the rest of its tools follow from that constraint. --- Source: https://foldkit.dev/elm/foldkit-vs-elm-side-by-side Section: Guides # Foldkit vs Elm: Side by Side ## Overview This comparison uses the same [pixel art editor](https://foldkit.dev/example-apps/pixel-art) in Foldkit and Elm. Both versions include grid drawing, undo and redo, brush, fill, and eraser tools, mirror modes, localStorage persistence, PNG export, keyboard shortcuts, and an application history panel. Foldkit applies the Elm Architecture in TypeScript on top of Effect. The familiar pieces remain: a Model, Messages, a pure update function, a view, and side effects returned for the Runtime to execute. The differences come from the host languages, their interop models, and the tools each framework builds around the architecture. Elm is the source of this architecture, and its language provides guarantees TypeScript cannot reproduce. Foldkit trades some of those guarantees for direct access to the TypeScript, Effect, browser, and npm ecosystems. Read them both The Foldkit version is in the [examples gallery](https://foldkit.dev/example-apps/pixel-art). The [Elm version source](https://github.com/foldkit/foldkit/tree/main/comparisons/pixel-art-elm) is an Elm 0.19 application with no npm dependencies. ## The Architecture You Already Know Most concepts translate directly: Elm Foldkit State `Model` Model declared with Schema Events `Msg` custom type Message Schema union Transitions `update : Msg -> Model -> ( Model, Cmd Msg )` `update(model, message): Update.Return` Side effects `Cmd Msg` Command for Message-driven work, plus other lifecycle primitives Event streams `Sub Msg` Subscription backed by an Effect Stream Boot data Flags decoded or accepted by `init` [Flags](https://foldkit.dev/core/init-and-flags) Schema supplied at boot JS interop Flags, ports, and custom elements Direct JavaScript APIs, [Mount](https://foldkit.dev/core/mount) , and CustomElement Nested state Nested Elm Architecture composition [Submodel](https://foldkit.dev/core/submodel) helpers for the same pattern ### Elm Msg The Elm application has 21 `Msg` variants: ``` type Msg = PressedCell Int Int | EnteredCell Int Int | LeftCanvas | ReleasedMouse | SelectedColor Int | SelectedTool Tool | SelectedGridSize Int | ToggledMirrorHorizontal | ToggledMirrorVertical | ClickedUndo | ClickedRedo | ClickedHistoryStep Int | ClickedRedoStep Int | ClickedClear | ClickedExport | FailedExportPng String | DismissedErrorDialog | ConfirmedGridSizeChange | DismissedGridSizeDialog | SelectedPaletteTheme Int | ToggledThemePicker ``` ### Foldkit Message union The current Foldkit application has 25 parent Messages: ``` const Message = defineMessageUnion({ PressedCell: { x: S.Number, y: S.Number }, EnteredCell: { x: S.Number, y: S.Number }, LeftCanvas: {}, ReleasedMouse: {}, SelectedColor: { colorIndex: PaletteIndex }, SelectedTool: { tool: Tool }, SelectedGridSize: { size: S.Number }, ToggledMirrorHorizontal: {}, ToggledMirrorVertical: {}, ClickedUndo: {}, ClickedRedo: {}, ClickedHistoryStep: { stepIndex: S.Number }, ClickedRedoStep: { stepIndex: S.Number }, ClickedClear: {}, ClickedExport: {}, SucceededExportPng: {}, FailedExportPng: { error: S.String }, GotErrorDialogMessage: { message: Dialog.Message }, GotThemeListboxMessage: { message: Listbox.Message }, GotToolRadioGroupMessage: { message: RadioGroup.Message }, GotGridSizeRadioGroupMessage: { message: RadioGroup.Message }, GotPaletteRadioGroupMessage: { message: RadioGroup.Message }, ConfirmedGridSizeChange: {}, GotGridSizeConfirmDialogMessage: { message: Dialog.Message }, CompletedSaveCanvas: {}, }) type Message = typeof Message.Type ``` The count differs because the component and effect boundaries differ. Foldkit has `SucceededExportPng` and `CompletedSaveCanvas` for Command completion, plus six `Got*Message` wrappers for two Dialogs, one Listbox, and three RadioGroups. The Elm version hand-rolls those controls and represents their application-facing events with four direct Msgs: `ToggledThemePicker`, `SelectedPaletteTheme`, `DismissedErrorDialog`, and `DismissedGridSizeDialog`. Both unions are the total input domain of their application update functions. Foldkit’s child wrapper Messages lead to another Message union and update function inside each Submodel. Elm custom-type values and Foldkit Schema values both have runtime tags. Schema also supplies runtime decoding and encoding when a Message is deliberately used at an external boundary. That does not make an application Message union a wire protocol automatically. A network boundary still needs an explicit Schema and compatibility policy. ## The Update Function The update functions have the same shape. ### Elm update ``` update : Msg -> Model -> ( Model, Cmd Msg ) update msg model = case msg of PressedCell x y -> case model.tool of Brush -> ( { model | grid = applyBrush x y model , undoStack = Grid.pushHistory model.grid model.undoStack , redoStack = [] , isDrawing = True } , Cmd.none ) Fill -> withSave { model | grid = Grid.floodFill x y model.selectedColorIndex model.grid , undoStack = Grid.pushHistory model.grid model.undoStack , redoStack = [] } Eraser -> -- ... ClickedUndo -> case model.undoStack of [] -> ( model, Cmd.none ) previousGrid :: olderGrids -> withSave { model | grid = previousGrid , undoStack = olderGrids , redoStack = model.grid :: model.redoStack } -- ... 19 more branches withSave : Model -> ( Model, Cmd Msg ) withSave model = ( model, saveCanvas (encodeSavedCanvas model) ) ``` ### Foldkit update ``` import { type Update } from 'foldkit' export const update = (model: Model, message: Message) => Message.match>(message, { PressedCell: ({ x, y }) => M.value(model.tool).pipe( withUpdateReturn, M.when('Brush', () => ({ model: evo(model, { grid: () => applyBrush(model, x, y), undoStack: () => pushHistory(model.undoStack, model.grid), redoStack: () => [], isDrawing: () => true, }), })), M.when('Fill', () => { const nextModel = evo(model, { grid: () => applyFill(model, x, y), undoStack: () => pushHistory(model.undoStack, model.grid), redoStack: () => [], }) return { model: nextModel, commands: [saveCanvas(nextModel)] } }), // ... ), ClickedUndo: () => Array.match(model.undoStack, { onEmpty: () => ({ model }), onNonEmpty: nonEmptyUndoStack => { const nextModel = evo(model, { grid: () => Array.lastNonEmpty(nonEmptyUndoStack), undoStack: () => Array.initNonEmpty(nonEmptyUndoStack), redoStack: Array.append(model.grid), }) return { model: nextModel, commands: [saveCanvas(nextModel)] } }, }), // ... 23 more handlers }) ``` `case msg of` becomes `Message.match`. Elm record updates become `evo` transformations. `( model, Cmd.none )` becomes `{ model }`. Elm enforces exhaustive pattern matching as part of the language. Foldkit obtains the same compile-time failure at a match written with `Message.match`. That is the required Foldkit update style, but TypeScript itself does not prevent someone from writing a non-exhaustive alternative. Elm record updates and `evo` both preserve references to unchanged nested values. The rendering section shows how each application uses that reference stability. ## The Model: Custom Types vs Schema ### Elm Model (type alias and custom types) The Elm Model uses custom types and `Maybe`: ``` type Tool = Brush | Fill | Eraser type MirrorMode = MirrorNone | MirrorHorizontal | MirrorVertical | MirrorBoth type alias Model = { grid : Grid , undoStack : List Grid , redoStack : List Grid , selectedColorIndex : Int , gridSize : Int , tool : Tool , mirrorMode : MirrorMode , isDrawing : Bool , hoveredCell : Maybe Position , exportError : Maybe String , paletteThemeIndex : Int , pendingGridSize : Maybe Int , isThemePickerOpen : Bool } ``` This hand-rolled UI stores Dialog visibility through the presence of `exportError` and `pendingGridSize`. The theme picker uses a separate `isThemePickerOpen` field. ### Foldkit Model (Schema struct) The Foldkit Model uses Effect Schema, `Option`, and child Models for its stateful Foldkit UI controls: ``` import { Schema as S } from 'effect' import { Dialog, Listbox, RadioGroup } from '@foldkit/ui' export const Model = S.Struct({ grid: Grid, undoStack: S.Array(Grid), redoStack: S.Array(Grid), selectedColorIndex: PaletteIndex, gridSize: S.Number, tool: Tool, mirrorMode: MirrorMode, isDrawing: S.Boolean, maybeHoveredCell: S.Option(Position), errorDialog: Dialog.Model, maybeExportError: S.Option(S.String), paletteThemeIndex: S.Number, gridSizeConfirmDialog: Dialog.Model, maybePendingGridSize: S.Option(S.Number), themeListbox: Listbox.Model, toolRadioGroup: RadioGroup.Model, gridSizeRadioGroup: RadioGroup.Model, paletteRadioGroup: RadioGroup.Model, }) ``` A Schema exists at runtime as well as in TypeScript. Foldkit can use it to validate flags and persisted values, encode selected data, and describe Models to framework tooling. The child component Models expose interaction state that the Elm application implements directly in its parent Model and views. Elm’s type system is sound and its custom types are compact. TypeScript is intentionally less strict, while Schema adds runtime boundary tools that a plain TypeScript type does not have. ## Ports vs Commands The pixel editor saves to localStorage and exports a PNG. The Elm implementation crosses into JavaScript for both operations. The Foldkit implementation performs them in Commands. ### Elm ports (the effect lives in JavaScript) The Elm side declares outgoing and incoming ports: ``` port module Main exposing (Msg(..), defaultModel, main, update) -- The Elm side: ports declare that JavaScript exists, nothing more. port saveCanvas : Encode.Value -> Cmd msg port requestExportPng : Encode.Value -> Cmd msg port exportPngFailed : (String -> msg) -> Sub msg -- In update: send a request out, receive the failure (if any) back -- as a Msg through the subscription. ClickedExport -> ( model, requestExportPng (encodeExportRequest model) ) FailedExportPng error -> ( { model | exportError = Just error }, Cmd.none ) ``` The JavaScript side subscribes to them in `index.html`: ``` // The JavaScript side, in index.html. This code is invisible to the // Elm compiler. If it throws, drifts out of sync with the encoder, or // forgets to call send(), Elm cannot know. app.ports.saveCanvas.subscribe(function (data) { try { localStorage.setItem(STORAGE_KEY, JSON.stringify(data)) } catch (error) { // Silently fail on storage errors } }) app.ports.requestExportPng.subscribe(function (request) { try { var canvas = document.createElement('canvas') var context = canvas.getContext('2d') if (context === null) { throw new Error('Canvas 2D context not available') } // ... paint request.pixels onto the canvas, then download ... link.click() } catch (error) { app.ports.exportPngFailed.send( error instanceof Error ? error.message : 'Failed to export image', ) } }) ``` The port declaration gives Elm a typed interface. The JavaScript subscriber remains outside the Elm compiler, so a renamed payload field or a missing `send` call is not checked against the Elm source. A JavaScript exception can still affect the host page; the boundary protects Elm code from directly calling arbitrary JavaScript, not the entire page from JavaScript failures. The export failure needs an incoming port so JavaScript can send `FailedExportPng` back to Elm. Saving is fire-and-forget in this application. ### Foldkit Commands (the effect lives with the app) Foldkit runs in the JavaScript ecosystem, so its Commands can use browser APIs and JavaScript libraries directly: ``` const SaveCanvas = Command.define('SaveCanvas', { args: { grid: Grid, gridSize: S.Number, paletteThemeIndex: S.Number, selectedColorIndex: PaletteIndex, }, messages: [CompletedSaveCanvas], execute: ({ grid, gridSize, paletteThemeIndex, selectedColorIndex }) => Effect.gen(function* () { const store = yield* KeyValueStore.KeyValueStore const data: SavedCanvas = { grid, gridSize, paletteThemeIndex, selectedColorIndex, } yield* store.set(STORAGE_KEY, S.encodeSync(SavedCanvasJsonString)(data)) return CompletedSaveCanvas() }).pipe( Effect.catch(() => Effect.succeed(CompletedSaveCanvas())), Effect.provide(BrowserKeyValueStore.layerLocalStorage), ), }) const ExportPng = Command.define('ExportPng', { args: { grid: Grid, gridSize: S.Number, paletteThemeIndex: S.Number }, messages: [SucceededExportPng, FailedExportPng], execute: ({ grid, gridSize, paletteThemeIndex }) => Effect.gen(function* () { const theme = PALETTE_THEMES[paletteThemeIndex] ?? PALETTE_THEMES[0] const canvas = document.createElement('canvas') const context = canvas.getContext('2d') if (Predicate.isNull(context)) { return yield* Effect.fail( FailedExportPng({ error: 'Canvas 2D context not available' }), ) } // ... paint each cell, then click a generated download link return SucceededExportPng() }).pipe( Effect.catchTag('FailedExportPng', error => Effect.succeed(error)), Effect.catch(() => Effect.succeed(FailedExportPng({ error: 'Failed to export image' })), ), ), }) ``` Each Command declares its arguments and result Messages. Its Effect can use typed failures and recovery operators before returning a Message to update. The application still needs to choose meaningful error behavior. Here `ExportPng` reports failure, while `SaveCanvas` intentionally converts storage failure into the same completion Message as success. The boundary trade-off Elm prevents application code from calling arbitrary JavaScript and makes interop explicit through ports or custom elements. Foldkit keeps update pure by convention and framework design, while Command bodies can call the host ecosystem directly. TypeScript cannot enforce Elm’s purity boundary. ## JSON: Decoders vs Schema Both applications restore a saved canvas from boot flags and persist it as JSON. ### Elm decoders and encoders Elm defines the type, decoder, and encoder separately: ``` init : Decode.Value -> ( Model, Cmd Msg ) init flags = case Decode.decodeValue savedCanvasDecoder flags of Ok saved -> ( { defaultModel | grid = saved.grid , gridSize = saved.gridSize , paletteThemeIndex = saved.paletteThemeIndex , selectedColorIndex = saved.selectedColorIndex } , Cmd.none ) Err _ -> ( defaultModel, Cmd.none ) savedCanvasDecoder : Decode.Decoder SavedCanvas savedCanvasDecoder = Decode.map4 SavedCanvas (Decode.field "grid" gridDecoder) (Decode.field "gridSize" Decode.int) (Decode.field "paletteThemeIndex" Decode.int) (Decode.field "selectedColorIndex" Decode.int) gridDecoder : Decode.Decoder Grid gridDecoder = Decode.array (Decode.array (Decode.nullable Decode.int)) -- And the encoder, written by hand in the other direction: encodeSavedCanvas : Model -> Encode.Value encodeSavedCanvas model = Encode.object [ ( "grid", encodeGrid model.grid ) , ( "gridSize", Encode.int model.gridSize ) , ( "paletteThemeIndex", Encode.int model.paletteThemeIndex ) , ( "selectedColorIndex", Encode.int model.selectedColorIndex ) ] ``` The compiler checks the values each function produces, but the decoder and encoder use independent string field names. A mismatch between `"gridSize"` and `"gridsize"` can compile. ### Foldkit Schema (one definition, both directions) Foldkit derives both directions from one `SavedCanvas` Schema: ``` // The Schema is the single source of truth. The decoder and the // encoder both fall out of it. They cannot drift apart. export const SavedCanvas = S.Struct({ grid: SavedGrid, gridSize: S.Number, paletteThemeIndex: S.Number, selectedColorIndex: PaletteIndex, }) export const SavedCanvasJsonString = S.fromJsonString( S.toCodecJson(SavedCanvas), ) export const flags: Effect.Effect = Effect.gen(function* () { const store = yield* KeyValueStore.KeyValueStore const json = yield* Effect.fromOption( Option.fromNullishOr(yield* store.get(STORAGE_KEY)), ) const decoded = yield* S.decodeEffect(SavedCanvasJsonString)(json) return Flags.make({ maybeSavedCanvas: Option.some(decoded) }) }).pipe( Effect.catch(() => Effect.succeed(Flags.make({ maybeSavedCanvas: Option.none() })), ), Effect.provide(BrowserKeyValueStore.layerLocalStorage), ) // Saving goes through the same Schema: // S.encodeSync(SavedCanvasJsonString)(data) ``` The Schema centralizes field names and value constraints. Encoding and decoding therefore evolve from the same definition. Version migrations and fallback behavior still belong to the application. ## Subscriptions Both frameworks derive external event streams from Model state. The mouse-release listener exists only while the user is drawing. ### Elm subscriptions ``` subscriptions : Model -> Sub Msg subscriptions model = Sub.batch [ Browser.Events.onKeyDown (keyboardDecoder model) , if model.isDrawing then Browser.Events.onMouseUp (Decode.succeed ReleasedMouse) else Sub.none , exportPngFailed FailedExportPng ] keyboardDecoder : Model -> Decode.Decoder Msg keyboardDecoder model = Decode.map5 KeyEvent (Decode.field "key" Decode.string) (Decode.field "ctrlKey" Decode.bool) (Decode.field "metaKey" Decode.bool) (Decode.field "shiftKey" Decode.bool) (Decode.field "altKey" Decode.bool) |> Decode.andThen (shortcutFor model) -- shortcutFor maps the decoded event to a Msg, or fails the -- decoder for keys the app does not care about. ``` ### Foldkit Subscriptions ``` export const subscriptions = Subscription.make()(entry => ({ keyboard: Subscription.persistent( Stream.fromEventListener(document, 'keydown').pipe( Stream.mapEffect(handleKeyboardEvent), Stream.filter(Option.isSome), Stream.map(option => option.value), ), ), mouseRelease: entry( { isDrawing: S.Boolean }, { modelToDependencies: model => ({ isDrawing: model.isDrawing }), dependenciesToStream: ({ isDrawing }) => Stream.when( Stream.fromEventListener(document, 'mouseup').pipe( Stream.map(() => ReleasedMouse()), ), Effect.sync(() => isDrawing), ), }, ), })) ``` Elm’s `Sub.batch` and Foldkit’s Subscription registry both describe the active set after each state transition. The runtime handles setup and teardown. Elm uses `Browser.Events` for keyboard and mouse input and an incoming port for export failure. Foldkit Subscriptions use Effect Streams, so the application can construct a Stream from browser APIs or a JavaScript client directly. Export failure does not need a Subscription because it is already a declared Command result. ## Rendering Performance Both implementations use reference-based memoization around the grid. Actual frame time depends on the production build, browser, and device, so this section compares the mechanisms rather than claiming a universal winner. ### Elm Html.Lazy and Html.Keyed ``` toolbarView : Model -> PaletteTheme -> Html Msg toolbarView model theme = div [ class "w-full md:w-44 flex flex-col gap-5 flex-shrink-0" ] [ lazy toolSection model.tool , lazy mirrorSection model.mirrorMode , lazy sizeSection model.gridSize , paletteSection model theme , lazy clearCanvasSection model.grid ] -- The canvas keys each row and wraps it in lazy5. A row only -- re-renders when one of its five arguments changes by reference. Html.Keyed.node "div" [ class "cursor-crosshair select-none w-full aspect-square flex flex-col bg-white" ] (Grid.toRows model.grid |> List.map (\( y, row ) -> ( String.fromInt y , lazy5 rowView y row previewColor (rowPreviewPositions y previewPositions) theme.colors ) ) ) ``` ### Foldkit createLazy and keyed ``` const lazyHeader = createLazy() const lazyToolPanel = createLazy() const lazyHistoryPanel = createLazy() const lazyRow = createKeyedLazy() // Each args array is compared element-by-element against the previous render. // If every arg is reference-equal, the view function isn't called at all. // evo() preserves references for unchanged Model fields, so the check just // works, and the builder is the same object every render, so passing it // through the args never invalidates the cache. export const view = (model: Model, h: HtmlBuilder): Document => ({ title: 'Pixel Art', body: h.div( [], [ lazyHeader(headerView, [h]), lazyToolPanel(toolPanelView, [ model.mirrorMode, model.tool, model.gridSize, model.selectedColorIndex, isGridEmpty(model.grid), theme, model.themeListbox, h, ]), canvasView(model, theme, h), lazyHistoryPanel(historyPanelView, [ model.undoStack, model.redoStack, currentGrid, model.gridSize, theme, h, ]), ], ), }) ``` `Html.Lazy.lazy` and `createLazy` reuse a previous rendered value when their function inputs remain referentially equal. Elm provides arity-specific helpers such as `lazy` and `lazy5`. Foldkit creates a lazy wrapper at module scope and passes an argument array. `createKeyedLazy` retains a separate cache for each stable key. ### The cell view, twice Both cell views attach Message values to event attributes: ``` rowView : Int -> Array Cell -> String -> List Int -> List String -> Html Msg rowView y row previewColor previewColumns paletteColors = div [ class "flex flex-1" ] (Array.toIndexedList row |> List.map (\( x, cell ) -> let displayColor = if List.member x previewColumns then previewColor else cellColor paletteColors cell in cellView x y displayColor ) ) cellView : Int -> Int -> String -> Html Msg cellView x y backgroundColor = div [ onMouseDown (PressedCell x y) , onMouseEnter (EnteredCell x y) , style "flex" "1" , style "background-color" backgroundColor ] [] ``` ``` const rowView = ( row: ReadonlyArray, y: number, previewColor: HexColor, previewPositions: ReadonlyArray, theme: PaletteTheme, h: HtmlBuilder, ): Html => h.div( [h.Style({ display: 'flex', flex: '1' })], Array.map(row, (cell, x) => { const isPreview = previewPositions.some( ([previewX, previewY]) => previewX === x && previewY === y, ) const displayColor = isPreview ? previewColor : resolveColor(cell, theme) return h.div([ h.OnMouseDown(PressedCell({ x, y })), h.OnMouseEnter(EnteredCell({ x, y })), h.Style({ flex: '1', backgroundColor: displayColor }), ]) }), ) ``` Neither view needs a component instance or a memoized event-handler closure for each cell. The coordinates are stored in the `Msg` or Message value dispatched by the event. ## UI Components The Elm version implements its Dialogs, RadioGroups, switches, and theme picker in the application. That keeps their state and events visible, but the application also owns their ARIA attributes, keyboard behavior, focus behavior, and transitions. The Foldkit version uses [Foldkit UI](https://foldkit.dev/ui/overview). Its Dialogs, RadioGroups, and Listbox are Submodels, while Switch is a controlled render helper. Selected values remain in the parent Model. Each stateful component reports changes through OutMessages that the parent folds into its own update. Elm application Foldkit application Dialog, RadioGroup, Switch, Listbox Implemented in the application Dialog, Listbox, and RadioGroup Submodels; controlled Switch helper Accessibility behavior Implemented and tested by the application Implemented and tested by Foldkit UI Selected values Parent Model Parent Model Transient interaction state Parent Model and view logic Child Models in the application Model Composition Nested architecture written by the app [Submodel](https://foldkit.dev/core/submodel) helpers standardize parent-child delegation The comparison is between the two checked-in applications, not the entire Elm package ecosystem. An Elm application can use community UI packages or organize nested state differently. ## Testing Both update functions are pure and easy to call directly. Their effect values differ. ### Elm update test (pure, but the Cmd is opaque) ``` suite : Test suite = test "undo restores the previous grid state" <| \() -> let -- The Cmd in each returned tuple is discarded with `_`. -- A Cmd is opaque: there is no way to look inside one, -- so there is no way to assert that ReleasedMouse -- actually triggered a save. ( afterPress, _ ) = update (PressedCell 0 0) defaultModel ( afterRelease, _ ) = update ReleasedMouse afterPress ( afterUndo, _ ) = update ClickedUndo afterRelease in Expect.all [ \model -> Expect.equal (Grid.cellAt 0 0 model.grid) Nothing , \model -> Expect.equal model.undoStack [] , \model -> Expect.equal (List.length model.redoStack) 1 ] afterUndo ``` `Cmd Msg` is opaque, so a direct `elm-test` unit test cannot compare or pattern-match the Command returned by update. The underscores discard it. Removing the save Command from `ReleasedMouse` would not fail this particular unit test. Program-level tools such as [elm-program-test](https://package.elm-lang.org/packages/avh4/elm-program-test/latest/) provide a higher-level way to simulate supported effects and interactions. That is a different test boundary from inspecting a `Cmd` value directly. ### Foldkit Story test (Commands are assertable values) ``` test('undo restores the previous grid state', () => { story( update, given(emptyModel), message(PressedCell({ x: 0, y: 0 })), message(ReleasedMouse()), Command.resolve(SaveCanvas, CompletedSaveCanvas()), model(model => { expect(model.grid[0]?.[0]).toEqual(Option.some(0)) expect(model.undoStack).toHaveLength(1) }), message(ClickedUndo()), Command.resolve(SaveCanvas, CompletedSaveCanvas()), model(model => { expect(model.grid[0]?.[0]).toEqual(Option.none()) expect(model.undoStack).toHaveLength(0) expect(model.redoStack).toHaveLength(1) }), ) }) ``` A [Story](https://foldkit.dev/testing/story) receives the named Commands returned by update. `Command.resolve` verifies that `SaveCanvas` is pending, supplies `CompletedSaveCanvas`, and dispatches that result Message. Removing the Command makes this Story fail at the resolution step. [Scene](https://foldkit.dev/testing/scene) adds interaction through Foldkit virtual DOM. It can query by accessible role, label, or text without starting jsdom. ## What You Give Up Moving from Elm to Foldkit gives up language-level constraints. **Enforced purity.** Elm code cannot call `Date.now()`, mutate an object, or perform I/O from update. TypeScript can. Foldkit’s architecture, conventions, and tests make the intended boundary visible, but they do not make an impure update impossible to write. **Elm’s runtime guarantees.** Elm models failure as data and prevents the ordinary null, undefined, and non-exhaustive failures common in JavaScript. Foldkit uses Schema, Effect, and explicit failure Messages, but TypeScript and npm dependencies can still throw or produce invalid values. **A smaller language and package surface.** Elm has one language, formatter, package manager, and constrained package API. TypeScript plus Effect and browser libraries has a larger set of concepts and more choices. **A smaller default runtime footprint.** Optimized Elm output is often compact. A Foldkit application includes Foldkit and Effect. The actual production size depends on the application and should be measured from the two builds being considered. ## What You Gain Foldkit gains direct access to the host ecosystem and additional framework tools. **JavaScript and npm access.** Browser APIs and compatible JavaScript packages can be imported into a Command, Mount, Subscription, ManagedResource, or CustomElement without a port layer. **TypeScript integration.** An embedded Foldkit program can share modules and types with its TypeScript host. Elm also embeds cleanly, but host communication crosses flags, ports, or custom elements. **Schema codecs.** One definition can provide the TypeScript type, runtime validation, and encoding and decoding for an external boundary. **Inspectable Commands.** Foldkit DevTools records named Commands beside the Messages that produced them, and Story and Scene tests can assert on the same values. **Effect services and control flow.** Commands can compose retries, timeouts, concurrency, resources, Layers, and typed failures from Effect. **First-party UI Submodels.** Foldkit UI supplies accessible components built with the same Model, Message, and update architecture as the application. ## Conclusion Elm and Foldkit share the application model, so the choice turns on the host environment and the guarantees you need. Choose Elm when its language, compiler, package constraints, and interop model fit the application. Those constraints provide purity and refactoring guarantees that a TypeScript framework cannot reproduce. Choose Foldkit when the application needs to remain in TypeScript, integrate directly with JavaScript libraries, or use Effect services while retaining the Elm Architecture. Foldkit standardizes that architecture and adds Schema, inspectable Commands, Submodels, DevTools, and testing tools around it. The [Elm source](https://github.com/foldkit/foldkit/tree/main/comparisons/pixel-art-elm) and [Foldkit source](https://github.com/foldkit/foldkit/tree/main/examples/pixel-art) remain recognizably the same kind of program. Their differences show which guarantees come from Elm the language and which structures Foldkit recreates in TypeScript. --- Source: https://foldkit.dev/core/architecture Section: Core Concepts # Architecture ## One State Tree In most TypeScript UI frameworks, each component manages its own state and effects. Foldkit keeps application state in one `Model` and sends every change through the same loop. This pattern is called [The Elm Architecture](https://guide.elm-lang.org/architecture/). You don’t need to know Elm to use it. Foldkit adapts the pattern for TypeScript and Effect so state transitions stay explicit and traceable. ## The Loop Every Foldkit app repeats the same cycle: 1. Something happens, and a `Message` records that fact. 2. `update` receives the current `Model` and the Message, then returns the next Model and any `Command`s to execute. 3. `view` renders the next Model as HTML, and the runtime executes the Commands. 4. User events and effect results produce more Messages, and the cycle begins again. The complete cycle looks like this: ``` +------> update -> Commands -----------+ | | | | v | | Model -> Subscriptions --------+ | | | | +-> ManagedResources --------+ | | | | v | | view -> Mounts ----------------+ | | | | v | | Browser -> events -------------+ | v | Runtime | | | v +<--------------------------------- Message ``` Five sources report through the Runtime: Commands, the Browser, Mounts, Subscriptions, and ManagedResources. When one produces a Message, the Runtime dispatches it back into `update`. ### Where Messages Come From - **Browser:** interactions with the rendered view, such as clicks and keypresses, produce Messages directly. - **Commands:** one-shot side effects such as HTTP requests, focus operations, `localStorage` writes, and navigation calls. The runtime executes each Command and sends its declared result back as a Message. Every Command has a name that appears in [DevTools](https://foldkit.dev/core/devtools), [tests](https://foldkit.dev/testing), and tracing. - **Mount:** imperative work scoped to the lifetime of an element in the live DOM. For example: portaling an overlay, attaching an observer, or handing an element to a third-party library. `Mount.define` runs an Effect that emits one Message at acquire. `Mount.defineStream` runs a Stream of Messages from listeners or observers. The runtime dispatches those results and runs the paired cleanup when the element unmounts. - **Subscriptions:** scoped Streams gated by a slice of the Model. The runtime keeps a Subscription alive while that slice holds its value, then starts a fresh scope when the value changes. A Subscription often turns an external source, such as timer ticks, `WebSocket` frames, or system theme changes, into Messages. It can also emit no Messages and maintain DOM state for its lifetime, such as setting `user-select: none` while a drag is active. - **ManagedResources:** stateful handles, such as a camera stream, a `WebSocket` connection, or a Web Worker pool, that exist while a slice of the Model holds a particular value. The runtime acquires and releases the handle and dispatches Messages for each lifecycle transition. Commands and Subscriptions can use the typed handle while it is live and receive `ResourceNotAvailable` rather than crashing when it is not. Resources sit beneath the loop instead of feeding it directly. They are app-lifetime dependencies such as an `RpcClient`, an analytics client, or a background compute worker. The runtime shares them with Commands, Subscriptions, and startup Flags, but Resources do not produce Messages themselves. These sources never mutate the Model. They report what happened with a Message, and only `update` decides the next state. If you want to know how the app reached its current state, follow the Messages. ## Definitions Use this table as a reference after you understand the loop: Concept Definition Model The single data structure that holds the entire application state. Message A fact about something that happened, such as a button click, a keypress, or a successful request with a payload. update A pure function that receives the current Model and a Message, then returns the next Model and any Commands to execute. view A pure function that renders the Model as HTML. Its event handlers construct Messages. Command A description of a one-shot side effect. The runtime executes it and sends the result back as one of its declared Messages. Mount Imperative work scoped to a live DOM element. It emits Messages through an Effect or Stream and cleans up when the element unmounts. Subscription A scoped Stream gated by a slice of the Model. The runtime restarts its scope when that slice changes. Resource An app-lifetime singleton shared with Commands, Subscriptions, and startup Flags. It is a dependency, not a Message source. ManagedResource A stateful handle scoped to a slice of the Model. The runtime manages its lifecycle, and Commands and Subscriptions can use it while it is live. Runtime The Foldkit engine that executes Commands, runs Subscriptions, manages Mount and resource lifecycles, and routes Messages back into update. Submodel A self-contained Model, Message, update, and Commands that a parent embeds and delegates to. A child can surface high-level facts to its parent through the optional `outMessage` field returned by update. ## The Restaurant Analogy Think of a Foldkit app like a restaurant. The waiter keeps a notebook: a running picture of everything happening right now. Table 3 ordered the salmon. Table 5 is waiting for dessert. When something happens (a customer flags the waiter, the kitchen rings the bell), the waiter hears about it, updates their notebook, and maybe writes a slip for the kitchen. The waiter doesn’t cook the salmon. They hand the slip to the kitchen, and the kitchen reports back when it’s done. Messages work the same way. “Table 3 asked for the check” is a fact given to the waiter, not an instruction. The waiter decides what to do: maybe bring the check immediately, maybe offer dessert first. The message stays the same either way. The restaurant analogy Use the analogy to remember who knows the state and who performs effects. The definitions above remain the literal contracts. Foldkit Restaurant Model The waiter’s notebook: the current state of everything Message Something that happens: “table 3 asked for the check” update The waiter: hears what happened, updates the notebook, maybe writes a slip view What the customers actually see: plates on the table, the check arriving Command A slip for the kitchen: “prepare the salmon” Mount Tableside flambé: rolled out to a specific table the moment its dish arrives, rolled away when the plate is cleared Subscription A standing order: “keep the coffee coming for table 5” Resource Kitchen equipment: the oven, the stand mixer, the deep fryer. Turned on when the kitchen opens and available to every dish. ManagedResource A specialty station: set up when the menu features the seafood special, broken down when the special ends Runtime The kitchen: does the work, reports back when done That’s the architecture in the abstract. The next page shows a complete counter application: the core of the loop (a Model, Messages, `update`, `init`, and `view`) wired together and running. --- Source: https://foldkit.dev/core/counter-example Section: Core Concepts # A Simple Counter Example ## See the Whole Loop This counter puts the core loop from [Architecture](https://foldkit.dev/core/architecture) into one small application. Its Model holds the count. Its Messages record button clicks. Its update function decides the next count, and its view renders the result. The example uses two files. `src/main.ts` holds the pure application definitions: Model, Messages, update, init, and view. Larger applications can split those definitions into focused modules. `src/entry.ts` remains the runtime boundary, so tests can import the application without starting it as a side effect. ``` import { Schema as S } from 'effect' import { Runtime, type Update } from 'foldkit' import type { Document, HtmlBuilder } from 'foldkit/html' import { defineMessageUnion } from 'foldkit/message' import { evo } from 'foldkit/struct' // MODEL export const Model = S.Struct({ count: S.Number, }) export type Model = typeof Model.Type // MESSAGE export const Message = defineMessageUnion({ ClickedDecrement: {}, ClickedIncrement: {}, ClickedReset: {}, }) export type Message = typeof Message.Type // UPDATE export const update = (model: Model, message: Message) => Message.match>(message, { ClickedDecrement: () => ({ model: evo(model, { count: count => count - 1 }), }), ClickedIncrement: () => ({ model: evo(model, { count: count => count + 1 }), }), ClickedReset: () => ({ model: evo(model, { count: () => 0 }) }), }) // INIT export const init: Runtime.ApplicationInit = () => ({ model: { count: 0 }, }) // VIEW export const view = (model: Model, h: HtmlBuilder): Document => ({ title: `Counter: ${model.count}`, body: h.div( [ h.Class( 'min-h-screen bg-white flex flex-col items-center justify-center gap-6 p-6', ), ], [ h.div( [h.Class('text-6xl font-bold text-gray-800')], [model.count.toString()], ), h.div( [h.Class('flex flex-wrap justify-center gap-4')], [ h.button( [h.OnClick(Message.ClickedDecrement()), h.Class(buttonStyle)], ['-'], ), h.button( [h.OnClick(Message.ClickedReset()), h.Class(buttonStyle)], ['Reset'], ), h.button( [h.OnClick(Message.ClickedIncrement()), h.Class(buttonStyle)], ['+'], ), ], ), ], ), }) // STYLE const buttonStyle = 'bg-black text-white hover:bg-gray-700 px-4 py-2 transition' ``` The entry imports those definitions and passes them to `Runtime.makeApplication`. `Runtime.run` then starts the application in the selected container. ``` import { Runtime } from 'foldkit' import { Model, init, update, view } from './main' const application = Runtime.makeApplication({ Model, init, update, view, container: document.getElementById('root'), }) Runtime.run(application) ``` Read the example once for its shape. The next four pages examine the [Model](https://foldkit.dev/core/model), [Messages](https://foldkit.dev/core/messages), [update](https://foldkit.dev/core/update), and [view](https://foldkit.dev/core/view) in order. Later pages extend the same counter with a delayed reset, automatic counting, and saved state to introduce side effects and ongoing work. Start with the Model, the single data structure that describes the application right now. --- Source: https://foldkit.dev/core/model Section: Core Concepts # Model ## One State Tree The Model is the complete application state in one immutable data structure. Everything the application can be at a moment lives here, rather than being divided between component-local and global stores. In the [restaurant analogy](https://foldkit.dev/core/architecture#the-restaurant-analogy), this is the waiter's notebook. The analogy is a memory aid; the literal contract is one state tree that every transition receives and returns. The counter defines its Model with [Effect Schema](https://effect.website/docs/schema/introduction/): ``` import { Schema as S } from 'effect' // MODEL const Model = S.Struct({ count: S.Number, }) type Model = typeof Model.Type ``` `S.Struct` creates the runtime Schema. `typeof Model.Type` derives the TypeScript type from that same definition, so the runtime and compiler agree on the Model’s shape. That runtime value matters because TypeScript types disappear after compilation. Foldkit uses the Model Schema to encode and decode state preserved across hot updates. The same Schema can validate unknown data at application boundaries. The counter starts with one field. When automatic counting becomes part of the application state, the Model grows to record it: ``` import { Schema as S } from 'effect' // When the counter gains auto-counting, // the Model grows to hold new state: const Model = S.Struct({ count: S.Number, isAutoCounting: S.Boolean, }) type Model = typeof Model.Type ``` Model the application, not the screen Store facts the application needs to remember. Values used only to render one frame can usually be derived in view instead of becoming another Model field. The Model describes the current state. Every change begins with a [Message](https://foldkit.dev/core/messages), a fact about something that happened. --- Source: https://foldkit.dev/core/messages Section: Core Concepts # Messages ## Facts, Not Instructions A Message records something that happened in the application. It does not prescribe the response. The update function decides what the fact means for the current Model. `ClickedIncrement` does not mean “add one.” It records that the user clicked the increment button. In this counter, update adds one. A later version may return a Command that obtains the next value elsewhere. The Message remains a stable account of the event. The counter has three Messages: ``` import { Schema as S } from 'effect' import { defineMessageUnion } from 'foldkit/message' // MESSAGE // defineMessageUnion() declares the union and its callable constructors together const Message = defineMessageUnion({ ClickedDecrement: {}, ClickedIncrement: {}, ClickedReset: {}, }) type Message = typeof Message.Type ``` Messages use verb-first, past-tense names such as `ClickedIncrement`, not `Increment` or `ADD_COUNT`. Prefixes make their causes easy to scan. `Clicked*` records clicks, and `Updated*` records input changes. Command results use `Succeeded*` or `Failed*` when the distinction matters, and `Completed*` otherwise. `Got*` is reserved for results lifted from a child [Submodel](https://foldkit.dev/core/submodel). The `defineMessageUnion()` helper declares the whole union in one place. Each key becomes a callable constructor on the union, so `Message.ClickedIncrement()` creates the value and `Message.match(message, handlers)` handles every variant exhaustively. Do not destructure the constructors. Keeping `Message` or `OutMessage` at the call site makes the owning domain explicit. Name the cause A Message says what happened, not what update intends to do next. That keeps the same fact useful when the application’s response changes. Messages describe what happened. The [update function](https://foldkit.dev/core/update) defines every resulting state transition. --- Source: https://foldkit.dev/core/update Section: Core Concepts # Update ## One Function Defines Every Transition The update function receives the current Model and a Message, then returns the next Model and any Commands for the runtime to execute. It is the only place application state changes. Update is pure. Given the same Model and Message, it returns the same result. It does not mutate state, call browser APIs, start timers, or make requests. That makes a transition direct to test: pass in the inputs and assert on the returned values. Use `Message.match` to handle the Message union. If you add a Message and omit its branch, TypeScript reports the missing case. No `default` branch silently absorbs a new variant. Use [Effect's `Match`](https://effect.website/docs/code-style/pattern-matching/) for other tagged unions, partial matches, fallbacks, and one handler shared across several tags. ``` import { type Update } from 'foldkit' import { evo } from 'foldkit/struct' // UPDATE const update = (model: Model, message: Message) => Message.match>(message, { ClickedDecrement: () => ({ model: evo(model, { count: count => count - 1 }), }), ClickedIncrement: () => ({ model: evo(model, { count: count => count + 1 }), }), ClickedReset: () => ({ model: evo(model, { count: () => 0 }) }), }) ``` Each branch describes one transition. `ClickedDecrement` and `ClickedIncrement` transform the current count. `ClickedReset` replaces it with zero. This version of the counter has no side effects, so all three omit `commands`. The branches build their next Model with [evo](https://foldkit.dev/best-practices/immutability#immutable-updates). Each named field receives a function from its current value to its next value. Omitted fields keep their existing values and references, so the same update style continues to work as the Model grows. Update returns a record containing the next Model and, when needed, an array of Commands. A Command describes one side effect, such as an HTTP request, timer, or browser API call. The [Commands](https://foldkit.dev/core/commands) page adds a delayed reset and puts the optional `commands` field to work. ## Returning Commands Return Commands beside the next Model from the Message branch that requests the work: ``` import { type Update } from 'foldkit' import { evo } from 'foldkit/struct' const update = (model: Model, message: Message) => Message.match>(message, { ClickedIncrement: () => { const nextCount = model.count + 1 return { model: evo(model, { count: () => nextCount }), commands: [PersistCount({ count: nextCount })], } }, CompletedPersistCount: () => ({ model }), }) ``` `ClickedIncrement` changes the count and asks the runtime to persist it. `CompletedPersistCount` records that the Command finished, but it has no more work to request, so that branch omits `commands`. An update, init, boot, or component helper that statically creates no Commands omits `commands`. When it computes a Commands collection, it returns that collection directly without checking whether it is empty. The [`foldkit/no-empty-commands-array`](https://foldkit.dev/tooling/oxlint-plugin#no-empty-commands-array) lint rule rejects only a literal `commands: []` property. ## Composing Results ### Keeping Results Together Keep an update-like result attached to the operation that produced it. Name the value after the operation and use dot access: ``` const homeInit = Home.init() return { model: { home: homeInit.model }, commands: Command.mapMessages(homeInit.commands, message => Message.GotHomeMessage({ message }), ), } ``` The same rule applies when a test consumes an update result: ``` const formSubmit = update(model, Message.SubmittedForm()) expect(formSubmit.model.status).toBe('Submitting') expect(formSubmit.commands ?? []).toHaveLength(1) ``` When the operation name collides with the function, use a trailing underscore such as `init_`. Do not destructure or rename `model`, `commands`, or `outMessage`. Dot access does not make an OutMessage impossible to ignore. It keeps the operation and its returned values visibly connected. Pass optional Commands directly to APIs that accept them, including `Command.mapMessages`. Use `result.commands ?? []` only when the next operation requires an array for spreading, concatenating, execution, or an assertion. ### Composing Update Steps TypeScript rejects this manual composition when the enclosing update returns `Update.Return`: ``` const dialogOpen = openDialog(model) return { model: evo(dialogOpen.model, { isSubmitting: () => false }), // Type error: with exactOptionalPropertyTypes, this property must be // omitted when dialogOpen.commands is undefined. commands: dialogOpen.commands, } ``` Every Foldkit template enables `exactOptionalPropertyTypes`. With that setting, the optional `commands` property may be absent. When the property is present, it must contain Commands. `dialogOpen.commands` has the type `Update.Commands | undefined`, so TypeScript rejects `commands: dialogOpen.commands`. This error often points to update results being composed by hand. When both operations update the same Model, express them as Steps and compose them with `Update.combine`: ``` return Update.combine(model, [ openDialog, stepModel => ({ model: evo(stepModel, { isSubmitting: () => false }), }), ]) ``` Manual unpacking of a child result usually means the site should use `Update.foldChild` or `Update.foldChildStep`. Use `Update.combine` when two or more operations transform the same Model and a later Step should receive the Model produced by an earlier Step. Name that parameter `stepModel` when an inline Step needs it: ``` return Update.combine(model, [ foldDialogClose, stepModel => ({ model: evo(stepModel, { isSubmitting: () => false }), }), ]) ``` `combine` appends the Commands to its returned array in Step order. The runtime forks those Commands independently, so an application must not depend on their execution or completion order. Do not wrap one Step in `Update.combine`; call that operation directly. ### Combining Independent Results Independent child inits are not a sequence because neither child updates the other child's Model. Initialize them separately and assemble the parent Model: ``` const homeInit = Home.init() const roomInit = Room.init(route) return { model: { home: homeInit.model, room: roomInit.model, }, commands: [ ...Command.mapMessages(homeInit.commands, toGotHomeMessage), ...Command.mapMessages(roomInit.commands, toGotRoomMessage), ], } ``` ## Preventing Lost OutMessages Use `Update.Return` for an update that cannot emit an OutMessage. TypeScript rejects assigning an OutMessage-producing result to it: ``` const childUpdate: Update.ReturnWithOutMessage< Child.Model, Child.Message, Child.OutMessage > = Child.update(model.child, message) // Type error: childUpdate may contain an OutMessage that this type cannot hold. const plainChildUpdate: Update.Return = childUpdate ``` This protects the OutMessage from being lost while a caller keeps only the Model and Commands. An OutMessage-aware return type also accepts a result that emitted nothing: ``` const plainUpdate: Update.Return = { model } const submodelUpdate: Update.ReturnWithOutMessage = plainUpdate ``` An OutMessage-aware caller can accept a plain result because an update is allowed to emit nothing. ### Returning an OutMessage When the OutMessage is already known while constructing a new result, include it directly: ``` return { model, outMessage: OutMessage.Closed() } ``` Use `Update.withOutMessage` when attaching an OutMessage to an existing plain result or when the value has the type `OutMessage | undefined`. If an operation already produced the plain result, pipe that named result into the helper: ``` const dialogClose = closeDialog(model) return pipe(dialogClose, Update.withOutMessage(outMessage)) ``` The object-spread alternative is easy to get wrong: ``` // Avoid: this writes outMessage: undefined and accepts a result that already has an OutMessage. return { ...dialogClose, outMessage } ``` `Update.withOutMessage` preserves `dialogClose.model` and `dialogClose.commands`. A defined value becomes `outMessage`; `undefined` leaves the property out. The update result must be a plain return, so the helper cannot overwrite an OutMessage another operation emitted. When constructing the plain result in the same expression and the value has the type `OutMessage | undefined`, pass the result first: `Update.withOutMessage({ model, commands }, outMessage)`. --- Source: https://foldkit.dev/core/view Section: Core Concepts # View ## Model In, HTML Out The view function turns the Model into HTML. Given the same Model, it produces the same output. It does not modify state or run Effects. Event attributes complete the loop. They produce Messages for the runtime to dispatch, and update decides what those Messages mean. The view remains a pure description of what the user should see and which facts an interaction can report. In the [restaurant analogy](https://foldkit.dev/core/architecture#the-restaurant-analogy), view is the meal on the table. The Model records the current facts; view presents them. ``` import type { Document, HtmlBuilder } from 'foldkit/html' // VIEW const view = (model: Model, h: HtmlBuilder): Document => ({ title: `Counter: ${model.count}`, body: h.div( [h.Class(containerStyle)], [ h.div( [h.Class('text-6xl font-bold text-gray-800')], [model.count.toString()], ), h.div( [h.Class('flex flex-wrap justify-center gap-4')], [ // OnClick takes a Message, not a callback. The Message doesn't // execute anything. It just declares what should happen on click. // Foldkit dispatches it to your update function. h.button( [h.OnClick(ClickedDecrement()), h.Class(buttonStyle)], ['-'], ), h.button( [h.OnClick(ClickedReset()), h.Class(buttonStyle)], ['Reset'], ), h.button( [h.OnClick(ClickedIncrement()), h.Class(buttonStyle)], ['+'], ), ], ), ], ), }) // STYLE const containerStyle = 'min-h-screen bg-cream flex flex-col items-center justify-center gap-6 p-6' const buttonStyle = 'bg-black text-white hover:bg-gray-700 px-4 py-2 transition' ``` No hook rules React functional components can hold local state and run effects through hooks, which introduces ordering rules. A Foldkit view has neither hooks nor local state. It is a function from Model to Html. ## The Document A `makeApplication` view returns a `Document`, not bare HTML. The Document contains the body to patch into the application container and the document-level state that should track the Model. Field Type Required What the runtime does with it `title` `string` Yes Writes it to `document.title` , so the browser tab tracks the current page. `body` `Html` Yes Patches it into the application container. `lang` `string` No Syncs it to `lang` on `` . Omit it and the current value stands. `dir` `'Ltr' | 'Rtl' | 'Auto'` No Syncs it to `dir` on `` , lowercased. Omit it and the current value stands. `canonical` `string` No Syncs it to `` , creating the tag if absent. Defaults to the current URL. `ogUrl` `string` No Syncs it to `` , creating the tag if absent. Defaults to `canonical` . Every field is a function of the Model, just like `body`. There is no imperative `setTitle` or separate head-management API. Return the values you want, and the runtime makes the document match after each render. A `makeElement` view returns `Html` directly. An embedded app does not own the page, so it cannot declare the title or document metadata. Everything outside this section applies to both kinds of view. See [Runtime](https://foldkit.dev/core/runtime#make-element) for when to use each one. ### Language and Direction `lang` and `dir` sync to the `` element. Drive them from the Model when the application can switch languages at runtime, just as `title` tracks the current page. ``` import type { Document, HtmlBuilder, TextDirection } from 'foldkit/html' // TRANSLATION const translate = (locale: Locale, key: string): string => { // Your catalog lookup. Foldkit does not ship translation. return catalog[locale][key] } // VIEW const languageTag: Readonly> = { English: 'en', Arabic: 'ar', Japanese: 'ja', } const textDirection: Readonly> = { English: 'Ltr', Arabic: 'Rtl', Japanese: 'Ltr', } const view = (model: Model, h: HtmlBuilder): Document => ({ title: translate(model.locale, 'PageTitle'), lang: languageTag[model.locale], dir: textDirection[model.locale], body: h.div( [h.Class('mx-auto max-w-prose p-6')], [ h.h1([], [translate(model.locale, 'PageTitle')]), localePicker(model.locale, h), ], ), }) ``` `dir` accepts `'Ltr'`, `'Rtl'`, or `'Auto'`. The runtime writes the corresponding lowercase attribute value. `Auto` delegates to the browser's first-strong-character heuristic. If the Model stores direction rather than deriving it, use the `TextDirection` Schema exported by `foldkit/html`. Neither field has a default. If view omits one, the runtime leaves the existing attribute alone. An application that never sets `lang` therefore keeps the value from `index.html`. The runtime can only synchronize these fields after the first render. Served HTML still determines what a crawler sees on first paint. If language is known per request, stamp `` into the HTML shell and let the runtime keep it current after startup. Use the `Lang` attribute on an individual element when only one passage differs from the page language. ### Canonical and Share URLs `canonical` and `ogUrl` keep `` and `` current as the route changes. If both are omitted, they resolve to the current URL. If only `canonical` is set, `ogUrl` uses the same value. Set them explicitly when the address bar does not identify the page you want indexed or shared. For example: later pages in a paginated list may point to the first page as canonical. On a server render, the default is the full request URL, including its query string. Set `canonical` explicitly when a query parameter is not part of the page's identity, such as a tracking parameter or session token. Otherwise, a crawler can treat each query variant as a separate canonical page. ## Typed HTML Helpers Every view receives `h`, an `HtmlBuilder` typed to the application's Message union. Elements, attributes, and handlers all come from this builder: ``` import type { HtmlBuilder } from 'foldkit/html' // Every view receives `h`, the typed Html builder, as its last argument. // Reach for `h.` to access elements, attributes, and event handlers. // Every callback is typed against your Message union, so `h.OnClick(...)` // only accepts your variants. const greeting = (name: string, h: HtmlBuilder) => h.div( [h.Class('flex flex-col gap-2')], [ h.h1([h.Class('text-2xl font-bold')], [`Hello, ${name}`]), h.button([h.OnClick(ClickedRefresh())], ['Refresh']), ], ) ``` The Message type follows the builder. If `h.OnClick` receives a Message outside the application union, TypeScript rejects it. The root runtime supplies its builder, and `Submodel.defineView` supplies one for each child view. Element builders take attributes first and optional children second. Omit the children argument when there are no children: `h.div([h.Class('divider')])`. Attributes remain required, so `h.div([])` represents an element with neither attributes nor children. `h.keyed` follows the same rule, with the key before the attributes and children. Void elements such as `h.img` and `h.br` accept attributes only. The `foldkit/no-empty-children-array` [lint rule](https://foldkit.dev/tooling/oxlint-plugin#no-empty-children-array) catches a trailing `[]` that carries no information. Application code cannot construct a builder. It only enters through a view parameter, which keeps its Message type aligned with the boundary that dispatches its handlers. Extracted view helpers should take `h: HtmlBuilder` as their last parameter. A helper that works under any parent can introduce a `ParentMessage` generic and accept `h: HtmlBuilder`. At module scope, where no view builder exists, `foldkit/html` exports `inertHtml`. It is an `HtmlBuilder`, so it can build elements and styling attributes but cannot express a Foldkit event handler. Its `Attribute` values can be used with any Message type, which lets a library publish reusable, handler-free attribute bundles. Import it as `ih` to distinguish it from the live builder passed to view. Markup built with `ih` may still vary with runtime data; inert means that it cannot dispatch a Message. Inside a view, use the builder supplied to that view. Inert HTML is inert to Foldkit dispatch, not to the browser. A raw DOM attribute can still trigger browser behavior. The [crash view](https://foldkit.dev/core/crash-view), for example, uses `h.Attribute('onclick', 'location.reload()')` because its `HtmlBuilder` cannot dispatch into a stopped update loop. Raw HTML, script sources, and script attributes need trusted content Several inputs run whatever you pass them, in the browser and in server-rendered HTML alike, and Foldkit does not sanitize them: - `h.InnerHTML` and `h.Srcdoc` render their strings as raw HTML. - A property named `innerHTML` from `CustomElement.define` writes raw HTML when the client assigns it, even though server rendering does not serialize that property. - `h.Attribute` writes a raw DOM attribute, including URL and event-handler attributes, without the sanitization a typed builder may apply. - A raw `onclick`-style attribute runs its string as script. - Text or `h.InnerHTML` inside a `script` or `style` element is emitted as trusted raw-text content. Script content executes, and style content can load resources and change the page. - The `src` of a ` ``` The script type makes the payload data rather than executable JavaScript. Foldkit escapes values that could close the script element. Hydration then parses and Schema-decodes the text. Flags are public HTML, not a place for secrets. ### Opting in from the client entry The client opts into the handoff in its entry (`src/entry.ts` in the examples): ``` Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID }) ``` `Runtime.run` always builds the DOM from scratch. An application with Flags supplies its client-only Flags Effect at that boundary: ``` Runtime.run(application, { flags }) ``` `Runtime.hydrate` accepts no client Flags producer. It reads the serialized Flags, calls the same `init`, and adopts matching server DOM nodes. Element identity, focus, scroll position, and media state survive while listeners and Mounts attach. A mismatched subtree is rebuilt from its nearest parent. Rebuilding discards the DOM identity and browser state that adoption preserves. Development logs a warning that points to nondeterministic Flags, `init`, or view output. Production rebuilds silently, so test hydration before shipping. Calling `hydrate` declares that a complete server handoff exists. If the handoff is invalid, startup stops before Foldkit adopts DOM and the page is put out of reach. [What a refusal does](#what-a-refusal-does) describes that state. This is safer than booting a different client Model over the server's HTML. Use `run` from a separate client entry when the page must also support a fresh SPA boot. `isHydratable` defaults to `true` for SSR and SSG. Set `isHydratable: false` only for static markup that no client will hydrate. The output then carries no application stamp, build id, Flags payload, key marker, or identity marker. `Runtime.hydrate` refuses it. ### Flags and what only the browser knows Hydration requires the server and browser to build the same first Model. Embedded Flags let the browser call `init` with the values the server used. Request-time SSR can derive Flags from the request, including the URL, headers, and cookies. Build-time SSG writes one file for every visitor, so its Flags must be universal and fixed at build time. Flags are public Every serialized Flag ships in the page's HTML. Never place credentials, private tokens, or other secrets in Flags. Browser-only facts do not belong in hydratable SSG Flags. For example: a theme stored in `localStorage`, the viewport width, and browser feature detection are unknown during the build. Start with a neutral Model on both sides. Load browser facts through a boot-time Command or Subscription after hydration. When a preference must affect the server HTML, make it request-visible, such as through a cookie, and use request-time SSR for that URL. ### The build id The build id does not make hydration correct. It makes hydration refuse when it would otherwise be incorrect. The server stamps the id on the rendered root. The client bundle carries the same value. Hydration compares them before it accesses the Flags payload text or adopts DOM. Different ids stop startup; matching ids allow hydration to continue. Most structural mismatches are safe because Foldkit rebuilds the affected subtree. The dangerous case is markup that has the same shape but a different meaning. For example: an old page may place `` where the new build places ``. Without a build check, hydration could preserve text entered before startup and submit it under the new field name. Flags create the same risk. A payload belongs to the deployment that rendered it. A new Schema may accept the old data even when its values now mean something different. The deployment supplies the id because Foldkit cannot infer it. Imported constants, configuration, and caller arguments can change a view's output without changing the view function. `@foldkit/vite-plugin` compiles the value from its `buildId` option or `FOLDKIT_BUILD_ID` into application code as `import.meta.env.FOLDKIT_BUILD_ID`. The client and server entries pass that value explicitly: ``` // vite.config.ts: the plugin compiles the value into application code, from // its `buildId` option or from FOLDKIT_BUILD_ID. foldkit({ buildId: process.env.DEPLOYMENT_SHA }) // src/entry.server.ts Server.renderToString(config, { flags, buildId: import.meta.env.FOLDKIT_BUILD_ID, }) // src/entry.ts Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID }) ``` Whatever value you pick, three things have to be true: - It is public. The id appears in the HTML sent to every visitor, so it must not contain a secret. - It identifies one deployment. Reusing an id makes a stale page look current and produces no warning. A commit or version is insufficient when the same revision can be deployed with different rendering inputs. The `ssr` and `ssg` scaffolds generate a fresh id whenever `FOLDKIT_BUILD_ID` is unset. - It reaches both builds. The client and server run as separate commands, so one build script must pass the same value to both. The scaffolds provide this coordination in `scripts/build.mjs`. A unique CI deployment id is a good source. A commit SHA or release tag is enough only when every deployment carrying it has identical rendering inputs. A hydratable render without an id fails with `MissingBuildId`. `Runtime.hydrate` also requires one. A static render with `isHydratable: false` needs none. Only a build takes the id from the deployment. The development server compiles the fixed value `development` into its server and client transforms. Development runs one live source session rather than producing independently deployable artifacts, so there is no deployment identity to derive. ### Why view identity cannot replace the build id A view identity names a module path and function. It does not capture imported constants, configuration, or caller arguments. View identity also ships in the client bundle. Adding a source hash would expose a digest of that source to every visitor. A reader could test candidates for a low-entropy server-only value by hashing each one, even when the client build removed the value itself. A deployment-supplied build id detects skew without hashing source files. ## Request-time SSR In development, enable the Vite host in `vite.config.ts`: ``` foldkit({ ssr: { serverEntry: '/src/entry.server.ts' } }) ``` Vite continues to serve the client entry, HMR, and assets. Requests that reach Foldkit become Web `Request` values and pass to `renderPage`. The returned Web `Response` provides the status, headers, and body. A hot update does not exercise hydration. HMR preserves the Model but rebuilds the DOM under the root. That DOM came from code that predates the edit. Reload the page to test hydration itself. The stamped root remains required during a hot update; without it, startup fails as it would on a fresh load. In production, build the client and server host separately. The host serves static assets first, imports the built entry, and sends `Server.toResponse(template, await renderPage(request))`. The [SSR example](https://github.com/foldkit/foldkit/tree/main/examples/ssr) uses an Effect `HttpServer` for this delivery layer. Caching personalized responses When Flags depend on the request, such as a cookie, authorization header, or locale, the rendered HTML belongs to that visitor. Set `cache-control` and `vary` so a shared cache cannot serve it to someone else. The SSR example uses `private, no-store` and `vary: cookie` because its initial count comes from a cookie. ## Build-time SSG An SSG host builds the browser bundle and server entry. A build script then calls `renderPage` once for every generated URL (`scripts/prerender.ts` in the SSG example): ``` for (const path of prerenderPaths) { const request = new Request(`https://example.com${path}`) const result = await serverEntry.renderPage(request) if (result._tag === 'Responded') { throw new Error(`Cannot write a Response for ${path} as static HTML`) } const html = Server.injectIntoTemplate(template, result.application) await writeRoute(path, html) } ``` Keep a copy of the template outside the build output, and take the built file as the template only while it still holds the placeholder. The generated `/` replaces `dist/client/index.html`, which is the file the client build left the template in, so a second run against one client build finds no `

` there and stops with `injectIntoTemplate found no exact

placeholder in the template`. The application's own `index.html` still has its placeholder and is never the file at fault. Reading the template before the loop is not enough on its own, because the loop that destroys it and the run that needs it are different runs. A static file is a body plus whatever headers the file host adds. It cannot carry a redirect, a 404, or per-response headers. Writing a `Responded` result to disk turns a redirect into an ordinary page at that URL. The build should fail on `Responded` and on any rendered status it cannot reproduce. The [SSG example](https://github.com/foldkit/foldkit/tree/main/examples/ssg) is the minimal reference. This website is the production-scale reference. Its prerender host uses the same `renderPage(Request)` contract, seeds route content through universal Flags, and writes every route as hydratable static HTML. ## Deploying A deployed SSG build is a directory of static files. Any static host or CDN can serve it as is. The hydration handoff already lives in the HTML. A deployed SSR application needs a host with two jobs: serve the built client assets and call `renderPage` for page requests. On Node, use the [SSR example's server](https://github.com/foldkit/foldkit/tree/main/examples/ssr/server) as the reference. It serves static files first and sends `Server.toResponse(template, await renderPage(request))` for everything else. ### Which methods reach the entry These rules apply to request-time SSR. An SSG deployment is a directory of files, so its static host owns method handling. An SSR host serves static files for `GET` and `HEAD`. Other application methods reach the entry, including `OPTIONS`. Under `vite dev`, a configured proxy route may answer first. Development and the production SSR host follow the same rule. A form action, `Server.Responded` reply, or CORS preflight should not work during development and fail after deployment. `OPTIONS` reaches the entry because a preflight concerns one application resource. Only the application knows its policy. The SSR example and scaffold answer with 204 and an `Allow` header as a placeholder. Replace that response with a real CORS policy before deploying. Preflight ownership follows `Access-Control-Request-Method`, not the URL suffix alone. For example: an `OPTIONS` request for `POST /submit.json` reaches the entry even though a `GET` for that path could name a static asset. An `OPTIONS` request without both `Origin` and `Access-Control-Request-Method` is not a CORS preflight. It reaches the entry regardless of its path. Vite still owns configured proxy routes, source modules, assets, and HMR. Its `server.cors` policy applies to those responses. Requests that fall through to Foldkit do not inherit that development-only policy. The entry's response headers therefore predict the deployed host. The plugin validates the request target before Vite or Foldkit handles it. Proxies still have the opportunity to answer before the server entry. Application `OPTIONS` requests that fall through still reach the entry. `CONNECT`, `TRACE`, and `TRACK` never reach the entry. The WHATWG `Request` constructor rejects them, so the host answers 405 with `Allow`. On Node, only `TRACE` reaches that rule. The HTTP parser answers `TRACK` with 400 before a handler runs. `CONNECT` arrives on its own event rather than as an ordinary request. ### Caching A static build is one file for every visitor, so it caches like any other static asset. Request-time rendering depends on its Flags. A route with universal Flags can use shared caching. A route whose Flags come from the request produces HTML for one visitor. A CDN or reverse proxy must not serve that response to the next visitor. Set the response headers in the server entry and confirm that every cache in front of it honors them. ### Fetch-native runtimes Cloudflare Workers, Deno, and Bun already use Web `Request` and `Response`, so they can run the entry without an adapter: ``` import { Server } from 'foldkit/experimental' import template from './dist/client/index.html' import { renderPage } from './dist/server/entry.server' export default { fetch: async (request: Request): Promise => Server.toResponse(template, await renderPage(request)), } ``` The platform serves the built client assets, and the handler covers page requests. Configure the bundler to treat the template's `.html` import as a string. Cloudflare's Wrangler CLI calls this a `Text` module rule. The same built server entry runs unchanged on each runtime. [Alchemy](https://alchemy.run) can provision and deploy the host. It is TypeScript-native infrastructure as code built on Effect. The Worker and its databases, object storage, or queues live in the same TypeScript program as the entry. Its [Cloudflare support](https://alchemy.run/cloudflare/) deploys the Worker directly. ## Using SSG and SSR together SSG and SSR are delivery policies, not separate Foldkit application types. A hybrid deployment can generate stable routes during the build and send the remaining URLs to a request-time host. Both hosts import the same server entry, and every page hydrates through the same client entry. For example: documentation and marketing pages can be generated at build time, while account pages and preview URLs render per request. Give each route one authoritative policy. Otherwise, one request may receive a generated page from the CDN and the next may receive a fresh page from the runtime host. ## What a refusal does Two things happen. Startup stops, and the page is put out of reach. ### Startup stops Every refusal stops before `init` runs. No Command, Subscription, or ManagedResource from this boot starts. For a build-id mismatch, Foldkit compares ids before accessing the Flags payload text, parsing its JSON, or Schema-decoding it. Stale Flags belong to the old deployment. Decoding them first would pass those values to current code before Foldkit noticed the mismatch. Flags-related refusals inspect the payload only far enough to identify the reported error. Every refusal reports a `[foldkit]` error that names the cause. Failures found while `makeApplication` resolves the container and stamped root throw immediately. Failures found after `Runtime.hydrate` starts use Effect's error reporting. Both reach the console and error monitoring. Neither provides an application hook because startup never reaches a Model. Build skew is one reason to refuse. The same policy also covers: - A Flags payload that is missing, duplicated, malformed, or rejected by the Schema. - A runtime id claimed by two roots, or more than one stamped root with distinct ids. - An empty root stamp, or a requested stamped root outside the document body light DOM. - A served root that lost its stamp. A generated client reaches this state when template insertion already replaced its `#root` placeholder, leaving neither the stamp nor the placeholder. One missing-container case is different. If `makeApplication` cannot find its container and the document contains no `data-foldkit-app`, `data-foldkit-build`, or `data-foldkit-flags`, then no server rendered the page. The application's `

` is simply absent, usually because of a typo or because the script ran too early. Foldkit reports the setup error and leaves the page alone. Every other refusal contains the page. This includes calling `Runtime.hydrate` with an existing container that has no stamped root, even on a page that was never server-rendered. Calling `hydrate` is the explicit claim that a handoff exists. Use `Runtime.run` for a fresh client boot. ### Page containment Foldkit marks the document body with `inert`, `aria-hidden`, and `data-foldkit-refused`. It opens a nondismissable modal shield beside the body and above existing top-layer content, including dialogs in closed shadow roots. The shield takes focus. Document-level input guards keep physical keyboard input from reaching stale handlers in the same document if older top-layer content requests focus. Author-owned dialogs remain open behind the shield. Containment does not call `close()` or dispatch `cancel`, either of which could run a stale listener while startup is failing. Pointer and physical keyboard input do not activate links, forms, or controls in that document. The shield asks the visitor to reload. The served DOM remains connected, and `data-foldkit-refused` is available for styling or monitoring. Nothing else in Foldkit sets that attribute. Nothing moves. Foldkit marks the existing body instead of wrapping the application root. Wrapping would reparent the subtree, call `disconnectedCallback` and then `connectedCallback` on every upgraded custom element, and reload every iframe. Marking the body avoids those lifecycle effects. The body is the containment boundary because every hydratable root sits inside it. `renderToString` refuses `html`, `head`, and `body` roots, and `hydrate` is reserved for an application that owns the page. ### Limits of containment Containment starts only after the client detects a refusal. It cannot undo earlier activity: - The parser may already have fetched subresources or run scripts from the old deployment. - A custom element may already have run `connectedCallback`. - A visitor may have interacted with the page before the client entry ran. A script can still submit a form programmatically despite `inert`. - Containment is not a script or global-event sandbox. Capture listeners on `window` or `document` run before an event reaches the shield. The browser may also dispatch global or top-layer events. - An iframe has its own document. Stale code can focus a control inside it, and physical keyboard input dispatched there does not reach the parent document's guards. - A timer or stale listener can open a new dialog after containment. That dialog enters the top layer above the shield. The shield covers top-layer content that existed when refusal began without invoking its lifecycle. ### Stale HTML and caches The build id acts only when the HTML and client bundle come from different deployments. A page cached whole usually references its original content-hashed bundle. Old HTML then loads old JavaScript, the ids match, and Foldkit does not refuse it. If the old assets have been deleted, the client script returns 404 and nothing boots. That is not a refusal and produces no `[foldkit]` error because Foldkit never runs. A mismatch requires stale HTML whose script resolves to current code. Shared caches, partially invalidated CDN nodes, and service workers that retain an application shell can create that pair. A running tab is not rechecked when a deployment lands. Keep stale HTML out of shared caches. Serve the page and its client bundle from the same deployment. ### Recovering from a refusal A refresh usually fixes a refusal by fetching HTML from the current deployment. A refresh cannot help while a CDN node or cache-first service worker keeps returning the old page. Recovery then depends on that cache updating. Foldkit cannot control the service worker lifecycle. Foldkit does not reload automatically and exposes no refusal hook. The runtime does not exist yet, so [`crash.report`](https://foldkit.dev/core/crash-view#crash-report) never runs. Container-resolution failures throw immediately; later hydration failures use Effect's error reporting. Automatic reload would also be unsafe. If stale HTML remains in the cache, each reload receives the same dead page and starts another loop. ## Limitations ### Rendering constraints Server rendering has no browser and runs only the first view over the initial Model. - Commands do not run during a server render. Data loaded by a Command therefore appears as the Model's pre-Command state, usually a loading state. Supply the data through Flags when it must appear in the server HTML. - Components that measure the DOM before deciding what to render, such as `Ui.VirtualList`, render their initial unmeasured state and fill in after hydration. - `makeElement` and `embed` applications do not hydrate. Server rendering supports page-owning `makeApplication` programs. - Ordinary element children under `template` cannot be server-rendered because browsers place them in a separate content fragment that the differ does not walk. Element children under `noscript` become raw text while scripting is enabled and cannot hydrate as the declared nodes. Keep template markup in the HTML shell. Use plain text, trusted `h.InnerHTML`, or shell markup for a noscript fallback. - Dynamic HTML tag names are normalized to lowercase, matching the elements `document.createElement` produces. SVG and MathML tag names are case-sensitive and must use their canonical spelling. `renderToString` refuses a foreign-content spelling that the HTML parser would adjust because `createElementNS` would preserve the original name on a fresh client render. ### DOM and form ownership Server HTML and client DOM must give each attribute, property, and content slot one owner. - `h.Style` owns individual CSS declarations rather than the whole `style` attribute. It accepts known camel-case or declaration names, plus custom properties beginning `--`, with one string value per declaration. It rejects `cssText`, Snabbdom lifecycle keys, duplicate names for one declaration, non-string values, `!important`, and syntax that can escape into another declaration. Server and client renders agree on effective CSS, though not necessarily on the exact attribute bytes or mutation history. Hydration avoids rewriting unchanged declarations. When a strict CSP blocks the parsed style attribute, the client reapplies declared properties through CSSOM. - Text entered into a controlled input before hydration yields to the Model when Foldkit reasserts controlled values. Controlled `value`, `checked`, `selected`, and `muted` state owns the corresponding live and default DOM state. Hydration, a fresh render, and `form.reset()` therefore agree. Removing the typed property clears that ownership or restores a remaining raw attribute. Ownership changes are observable DOM writes, so a MutationObserver may report them. Element identity, focus, and page scroll survive. - A controlled `h.Value` cannot share a `textarea` or `output` with declared children because both own the element's content. Keep either the controlled value or the children. This rule also applies to client-only rendering. - A raw `h.Attribute` and a typed builder cannot name the same attribute on one element. `h.Style` likewise cannot share an element with a raw `style` attribute. Keep one owner for each piece of state. - A typed reflected builder is client-only when the HTML element's native interface does not own that property. For example: spreading `h.Type('button')` onto a `div` creates an expando, so server rendering omits it instead of creating an attribute that a fresh client render would not. Use the matching element when the value must appear in markup, or use an intentional raw `h.Attribute`. - A `CustomElement.define` property named `value` cannot control a native `select` in a server-rendered view. A fresh client assigns the property before the options exist, while hydration assigns it after the parser has created them. The two writes can select different options. Property factories belong on the Custom Element they declare. Use `h.Value` so a native select has one controlled selection. ### Custom Elements Custom Elements may upgrade before hydration. These rules divide state between the component and the view. - Attributes added by a Custom Element's `connectedCallback` survive when the view does not declare them. Component-added class tokens and style properties also survive when the view uses `h.Class` and `h.Style`. A raw `h.Attribute('class', ...)` or `h.Attribute('style', ...)` owns the whole attribute and replaces component additions. - Component-built light DOM survives when the view declares no content. Foldkit adopts that childless host. When the view declares text, children, or `h.InnerHTML`, Foldkit replaces the host and builds the declared content while the new element is detached. The old host disconnects, and the new host has a new DOM identity. It connects once with the view content in place, as it does during a fresh render. This boundary is necessary because a browser may connect the old component before parsing its server content. Hydration cannot distinguish that content from nodes the component inserted and retained, and clearing the old host could let a child's `disconnectedCallback` mutate it during reconciliation. - Keep lifecycle DOM writes within the Custom Element's own host or shadow root. Hydration resamples view-owned element and text state after lifecycle callbacks. It does not sandbox callback code or rescan structure that a component changes elsewhere. - Declared custom-element properties are client behavior, not markup. They apply after hydration and never serialize as attributes. A component property named `id` or `title` stays client-side, while `h.Id` and `h.Title` still serialize the reflected attributes shared by all elements. Native elements continue to reflect their standard properties. For example: a server-rendered `