Foldkit Plus

What is Foldkit Plus about?

Foldkit Plus provides a collection of modular packages that augment a Foldkit application. Each package adds a specific capability—remote caching, offline sync, URL mirroring, form generation, CRUD operations, rich‑text editing, page building, server‑side rendering, or AI‑agent interfaces—without introducing a second state machine. All extensions operate on the same Model‑Message‑update core, preserving a single source of truth.

How to use Foldkit Plus?

1. Install the meta‑package (or individual packages) using npx:

   npx --legacy-peer-deps foldkit-plus setup
   

   The command inspects your project, prints the exact pnpm, npm or yarn installation commands, and adds required effect/foldkit version overrides.
2. Add the needed packages – for example foldkit-agent, foldkit-remote, foldkit-sync, foldkit-mirror, foldkit-ssr, etc.
3. Define your application with a Model, Message union, and a pure update function.
4. Create Surfaces to expose slices of the model and the messages a feature may emit.
5. Compose packages: attach Mixins for styling/behaviour, Mirrors for URL or KV storage, Sync for offline collaboration, Remote for server‑derived state, Agent for LLM or tool access, and SSR for resumable pages.
6. Run demos (pnpm demo) or start a specific example (pnpm dev examples/todo-app).

Key Features of Foldkit Plus

• Single‑owner architecture – all extensions share the same model, avoiding duplicated reducers.
• Agent‑native integration – expose existing messages to LLMs or other agents via MCP/WebMCP adapters.
• Local‑first replication – foldkit-sync + foldkit-durable enable offline editing, conflict resolution, and eventual consistency.
• Remote cache – foldkit-remote provides normalized server data, optimistic mutations, and live updates.
• URL & KV mirroring – foldkit-mirror keeps filters, drafts, or preferences in the URL or local storage.
• Rich‑text & page builder – Semantic document model with blocks, footnotes, tables, and a drag‑and‑drop page composer.
• CMS workflow – drafts, revisions, scheduled publishing, and a static‑site generator built on top of the same model.
• Data grid – virtualized grid for 100k+ rows with focus, selection, and inline editing.
• Server‑side rendering – foldkit-ssr hands over the Model to the server for resumable pages.
• Typed UI composition – Mixins and Bundles let you style or add behaviour without owning state.

Use Cases of Foldkit Plus

• Building a collaborative todo list or Kanban board that works offline and syncs across devices.
• Creating a headless CMS with real‑time preview, drafts, and scheduled publishing.
• Developing AI‑augmented applications where LLMs can read and write to the app via MCP.
• Implementing rich‑text editors or page builders for documentation platforms.
• Deploying a data‑intensive dashboard with a virtualized grid handling 100k+ rows.
• Rendering Foldkit apps on the server for SEO‑friendly pages and fast hydration.
• Providing a unified API surface for external agents to interact with your domain (e.g., adding items via voice assistants).

FAQ

Q: Do I need to import all packages? A: No. Each capability is a separate package; install only what you need and compose them through foldkit-surface.

Q: How does state stay consistent across agents, sync, and remote? A: All extensions operate on the same Model through the single update function. Agents emit messages that update handles, Sync replays those messages, and Remote reconciles server facts into the model.

Q: Can I use Foldkit Plus with existing React projects? A: Yes. foldkit-react and foldkit-react-codegen let you embed Foldkit views in React or compile them to TSX.

Q: What Node version is required? A: Packages target Node 22 for foldkit-durable core; most client‑side packages work in any modern browser.

Q: How do I configure the server side for Remote or Durable? A: Install the server adapters (foldkit-remote-server, foldkit-remote-drizzle, foldkit-durable) and follow the example in examples/cloudflare for a full stack setup.

Q: Is there a guide for a quick start? A: The examples/todo-app demo is the recommended entry point; run pnpm demo to see the whole system in action.

foldkit-plus

Packages that extend a Foldkit application outward — to agents, servers, other devices, the URL, and design systems — without giving it a second place to keep state.

A Foldkit application is one state machine: a Schema-typed Model, a Message union naming everything that can happen, and one pure update function that turns a Message into the next Model and some Commands. That shape is easy to reason about, test, and replay. It gets lost the moment an app grows a cache in a hook, a store in the URL, a tool handler that re-implements a transition, or a sync layer with its own reducer.

Everything in this repository keeps the one state machine. An agent can only send Messages update already handles. Server data lives in the Model and is reconciled by update. Replicas replay the same Messages through the same update. The URL and local storage mirror a slice of the Model; they never own one. Views are styled from outside without forking. Each package answers one question, and they compose because they meet at explicit application boundaries.

The website: foldkit-plus.pages.dev has each package's guides and API reference, and the demos, each an example from this repository built as static files. Those with a server run it in your browser, shared by every tab, so nothing you do leaves it:

• A blog studio and its site (examples/cms): Drafts beside the row, revisions, scheduled publishing and a page builder, with the public site rendered at build time.
• Two devices, one registry (examples/registry): Two devices edit 10,000 products in a data grid, offline and in conflict, and agree once both are back.
• Pages two tabs edit at once (examples/pages): Rich text two people edit at the same time, online or not, converging through one journal.
• A rich text playground (examples/richtext-playground): One document with movable blocks, anchored discussions, images, tables, code, toggles and footnotes, every edit a transition of the Model.
• A todo list an agent can use (examples/todo-app): One application definition drives the view, the tools an agent calls, the document replicas share, and the policy the server enforces.
• A Twitter clone, Chirp (examples/chirp): Posts declared once as Entities, guarded on the server, served through Remote, posted and edited through forms built from the same input, and liked in one round trip.
• A data grid over 100,000 rows (examples/data-grid): A grid that owns focus, selection, columns and the open editor, while the application owns every row.
• Eight widgets from shared primitives (examples/widgets): Once the capabilities exist, a family of widgets gets cheap: each one is a Bundle placement plus Behaviors on a shared Collection description, with no bespoke state machine.

Choose who owns the state

A Surface can observe several owners. Observing a field does not grant a second package permission to change it outside its owning transition.

intent → Message → update → Model → Projection / Surface → consumer
                      |
                      └→ Command → result Message → update

Sixty seconds of code

Start with one mechanism: an inspectable boundary around an existing Model.

The fastest way to see how the packages compose is to watch several of them reuse one application declaration. Assume Model, Message, initial, and update are an ordinary Foldkit todo app you already wrote. Everything around them derives from the same state machine; none of it introduces a second reducer.

import { Schema } from 'effect'
import { Agent } from 'foldkit-agent'
import { Mirror } from 'foldkit-mirror'
import { Capability, Slot, Slots, Style } from 'foldkit-mixins'
import { SurfaceView } from 'foldkit-mixins-surface'
import { MessageSet, Module, Projection, Surface } from 'foldkit-surface'
import { DocumentId, Sync } from 'foldkit-sync'

type Principal = { readonly role: 'owner' | 'guest' }
const isOwner = (principal: Principal) => principal.role === 'owner'

// 1. This is still the application: one Model, one Message union, one update.
// Surface adds typed references and inspection metadata; it does not add runtime state.
const App = Surface.application({ Model, Message, initial, update })

// 2. A Surface is a public boundary for a feature: what it may observe and cause.
// A renderer bound to Board can only construct these two Messages.
const Board = App.surface('Board', {
  model: ({ model }) => ({ todos: model.todos, filter: model.filter }),
  messages: [Message.ToggledTodo, Message.DeletedTodo],
})

// A read-only Surface can be reused by something that only needs context.
const Overview = App.surface('Overview', {
  model: ({ model }) => ({ todos: model.todos, filter: model.filter }),
})

// 3. Mixins separate "where customization is allowed" from "what gets attached there."
//
// BoardSlots is the view's public customization contract. It renders nothing by
// itself. It only names the places the view agrees other code may extend later:
// `root` will be the outer <section>; `list` will be the <ul>.
// Capabilities describe what kind of element lives at each point so incompatible
// Styles or Behaviors can be rejected instead of silently doing the wrong thing.
const BoardSlots = Slots.define({
  root: Slot.make({ capability: Capability.Container }),
  list: Slot.make({ capability: Capability.Collection }),
})

// Style is data written against that slot contract. Nothing is applied yet, and
// BoardStyle cannot read or change application state. Because it is created with
// `forSlots(BoardSlots)`, misspelling a slot or styling one Board never published
// is a type error rather than a convention.
const BoardStyle = Style.forSlots(BoardSlots)({
  root: Style.class('todo-board'), // contribute a class to the `root` slot
  list: Style.inline({ margin: '0', padding: '0', listStyle: 'none' }), // style `list`
})

// SurfaceView.define ties three boundaries together:
//   Board      -> the projected Model this view receives and the Messages it may emit
//   BoardSlots -> the places outside customization may attach
//   render fn  -> the actual markup
//
// So `model` is not the whole application Model; it is Board's { todos, filter }.
// And `h` is typed to the Messages Board declared above.
export const BoardView = SurfaceView.define(Board, BoardSlots, (model, slots, h) =>
  h.section(
    // `.attrs()` is the handoff point between markup and Mixins. It resolves the
    // view's own attributes plus every Style/Behavior attached to `root` into
    // ordinary Foldkit attributes for this <section>.
    slots.root.attrs(),
    [
      h.ul(
        // Same idea here: this exact DOM position is the published `list` slot.
        slots.list.attrs(),
        model.todos.map(todo => h.li([], [todo.title])),
      ),
    ],
  ),
).pipe(
  // Attach appearance from the outside. BoardView never imports CSS decisions into
  // its markup, so styles can be swapped/composed without copying the component or
  // adding a growing collection of styling props.
  Style.attach(BoardStyle),
)

// Behavior can attach element-level interaction through those same slots. It may
// contribute attributes, event handlers, or a Mount, but it still owns no Model;
// application state and transitions remain Model / Message / update.

// 4. Sync declares ownership of one writable slice and the facts that change it.
// Projection.pick is writable because checkpoints must install back into Model;
// replay still runs these Messages through the application's own update.
const TodoSync = Sync.forApplication(App)
  .withPrincipal<Principal>()
  .make({
    documentId: DocumentId.make('todos'),
    shared: Projection.pick(App.model.todos),
    durable: MessageSet.make(App, [
      Message.SubmittedTodo,
      Message.ToggledTodo,
      Message.DeletedTodo,
    ]),
    authorize: {
      // Policy lives on the contract and is enforced by the server journal.
      DeletedTodo: ({ principal }) => isOwner(principal),
    },
  })

// The server gets codecs, empty snapshot, replay, and authorization from Sync.
// There is no second server-side reducer to keep in agreement.
TodoSync.journalContract()

// 5. First specialize the Agent API to this application and Principal type.
// `forApplication(...).withPrincipal(...)` does NOT create an agent; it creates
// a typed builder whose helpers know App's Model, Message union, and Principal.
const AgentBuilder = Agent.forApplication(App).withPrincipal<Principal>()

// `make` creates the concrete agent contract that MCP/WebMCP/A2A/etc. can serve:
// what this agent sees, which existing Messages it may cause, and their policy.
const AssistantAgent = AgentBuilder.make({
  context: Overview,
  messages: AgentBuilder.expose(Message, {
    RequestedTodo: Agent.variant({
      name: 'add_todo',
      description: 'Add a todo with the given title',

      // The protocol input can be smaller than the internal Message. The call's
      // invocation id rides on the intent, and the Command copies it onto the fact.
      input: Schema.Struct({ title: Schema.String }),
      toMessage: ({ title }, { invocation }) => ({ title, requestId: invocation.id }),

      // RequestedTodo is an intent. The tool call completes when update later
      // applies the durable fact that carries this call's id: two calls adding
      // "Milk" each finish on their own todo, which a title could not tell apart.
      completion: {
        success: Message.SubmittedTodo,
        correlate: (_, result, { invocation }) => result.requestId === invocation.id,
      },
    }),
    ToggledTodo: { name: 'toggle_todo', description: 'Toggle a todo' },
    DeletedTodo: {
      name: 'delete_todo',
      description: 'Delete a todo (owner only)',
      // Same rule, checked early at the agent boundary; the journal still owns trust.
      authorize: ({ principal }) => isOwner(principal),
    },
  }),
})

// 6. Mirrors do not own state. They are secondary representations of Model fields.
const Filters = Mirror.url(App, {
  name: 'filters',
  fields: [App.model.filter], // linkable: ?filter=active
})
const Prefs = Mirror.kv(App, {
  key: 'todo/prefs',
  fields: [App.model.draft], // remembered on this device
})

// 7. The architecture itself is data. Validate ownership/capability relationships,
// or turn the same declarations into documentation and tooling input.
const Project = Module.make(App, [
  Board,
  Overview,
  TodoSync,
  AssistantAgent,
  Filters.contract,
  Prefs.contract,
])

Module.validate(Project) // []
Module.toMermaid(Project) // architecture generated from the declarations above

The code is large because the point is composition, not because any one package requires all of it.

1. The application stays the center. Model, Message, update, Commands, Submodels, and Mounts still mean what they mean in Foldkit.
2. Surface makes boundaries explicit. A Projection says what a consumer may observe; a Message subset says what it may cause. Those declarations are data, so other packages can reuse and inspect them.
3. Extensions reuse application semantics instead of copying them. Agents expose existing Messages, Sync replays them, Mirror represents Model fields elsewhere, and Mixins extends views without owning state.
4. Ownership stays singular. A URL mirror does not become a URL store; a replica does not grow a second reducer; a Style does not become view state.
5. The architecture itself becomes inspectable. Module.validate catches conflicting ownership, and Module.toMermaid turns the declarations into documentation or tooling input.

State changes take exactly two paths, and they are not equal. Ordinary application transitions travel Message → update. Everything else, such as a Sync checkpoint, a Mirror restoration or a Remote cache write, installs an already-derived value through a structural seam (ModelRef.set/modify, WritableProjection.set). A setter is infrastructure, not a second update; see Who changes application state, and how.

The important part is what is missing: no agent reducer, sync reducer, URL store, persistence state machine, server copy of the shared schema, or forked component just to restyle it.

foldkit-remote is deliberately not in this block. Remote is easiest to understand with an actual server-owned entity and query; see the Remote example or the kitchen-sink for that path. For the running version of this app, follow the todo app.

The sample above is typechecked in examples/todo-app/test/readme.test-d.ts, so the front page cannot quietly drift from the API.

Which package do I need?

If a term below is new, the glossary defines each one in a line.

foldkit-surface is the shared semantic seam for Agent, Remote, Sync, Mirror, and the Surface/Mixins bridge. It is not a mandatory base class for the whole repository: foldkit-durable, core foldkit-mixins, and the protocol/UI adapters can stand on their own and meet Surface-backed packages at explicit boundaries.

How they fit together

The arrows are integration boundaries, not new application state machines. Agent projects application capabilities. Remote reconciles server facts into the Model. Sync replays application Messages against an authoritative server order. Mirror keeps a secondary representation of Model fields. Mixins extends view structure without touching Model state. Primitives packages reusable browser and clock behaviour without hiding state. Entity declares a domain once as plain values; Remote, the Drizzle binding, and Form read it, and Crud joins a form to a Remote operation. Form and Crud own their submodel transitions inside the parent Model; Entity describes structure without holding runtime state. Durable can also be used independently as an ordered server journal.

The rule that makes the whole graph composable is one owner per datum:

That ownership rule is more important than the package boundaries. A single Surface may read across local state, Remote state, and Submodels because a Surface is an observation/capability boundary, not a second owner.

Try it

Start with examples/todo-app. It is the browser version of the architecture above: local-first state, owner-only rules, WebMCP tools, a linkable filter, and view composition around one Foldkit application.

For the broadest integration trace, use examples/kitchen-sink. For one concept at a time:

The application examples print transcripts with important lines pinned by tests. pnpm demo runs the root integration sequence; run the CMS demo separately. The examples index gives the recommended reading order.

Install

Tell your coding agent to run:

npx --legacy-peer-deps foldkit-plus setup

It reads your project and prints what to install with your package manager, the effect or foldkit version that needs changing, a .gitattributes that keeps LF line endings when the project has none, the agent skill, and which package does which job. By hand, foldkit-plus brings every package at once, each under a subpath named for it (foldkit-plus/remote-server). Foldkit takes Effect ~4.1.0 and these packages are tested on 4.1.0, so pin every Effect package to it first, to keep one copy of each, as this repository's pnpm-workspace.yaml does (setup prints the fields for npm, Yarn and Bun too):

{
  "pnpm": {
    "overrides": {
      "effect": "4.1.0",
      "@effect/platform-browser": "4.1.0",
      "@effect/platform-node": "4.1.0",
      "@effect/platform-node-shared": "4.1.0",
      "@effect/sql-sqlite-node": "4.1.0"
    },
    "peerDependencyRules": {
      "allowedVersions": { "effect": "4.1.0", "@effect/platform-browser": "4.1.0" }
    }
  }
}

pnpm add --save-exact effect@4.1.0 foldkit@0.170.0 @effect/platform-browser@4.1.0 foldkit-plus

Or install the pieces for the boundary you are adding; the packages are designed to be adopted independently.

# typed application boundaries
pnpm add foldkit-surface

# agent capabilities + one protocol adapter
pnpm add foldkit-agent foldkit-agent-webmcp

# normalized server-owned state
pnpm add foldkit-surface foldkit-remote
pnpm add foldkit-remote-server foldkit-remote-drizzle drizzle-orm # optional server compilation

# local-first replicated state
pnpm add foldkit-surface foldkit-sync foldkit-durable

# URL / local key-value representations
pnpm add foldkit-mirror

# reusable Submodels placed with every part wired
pnpm add foldkit-bundle foldkit-bundle-surface foldkit-surface

# a domain declared once, forms from an operation's input, and edit screens
pnpm add foldkit-entity foldkit-form foldkit-mixins-form
pnpm add foldkit-guard # who may do what, declared on the domain and enforced on the server
pnpm add foldkit-crud foldkit-remote # an editor, list, detail, and remover over Remote
pnpm add foldkit-mixins-crud # draws a list as a table and a detail as a description list
pnpm add foldkit-cms # content types, drafts beside the row, and a derived lifecycle
pnpm add foldkit-cms-drizzle drizzle-orm # its server: the audience boundary, drafts, and a publish that is whole

# an interactive data grid, and the accessible view that draws it
pnpm add foldkit-data-grid foldkit-mixins-data-grid

# rich text: the document, the editor on the page, Markdown and code
pnpm add foldkit-richtext foldkit-richtext-dom foldkit-mixins-richtext
pnpm add foldkit-richtext-markdown foldkit-richtext-code

# server rendering that hands the Model over
pnpm add foldkit-ssr

# ready-made primitives: media, timers, sockets, observers, clipboard
pnpm add foldkit-primitives

# responsive images, their variants, and icons as data
pnpm add foldkit-media

# view extension points
pnpm add foldkit-mixins foldkit-mixins-surface

# React interop in either direction
pnpm add foldkit-react react react-dom
pnpm add -D foldkit-react-codegen # views to TSX source

Other agent adapters are foldkit-agent-mcp, foldkit-agent-a2a, and foldkit-agent-native; foldkit-mixins-ui adapts compatible @foldkit/ui components.

foldkit and effect are peer dependencies. These packages ask for effect@^4.1.0 and are tested on 4.1.0; Foldkit 0.170.0 itself asks for effect@~4.1.0 and @effect/platform-browser@~4.1.0. Each @effect/* release peers on an effect at least its own version, so the overrides above hold the application at one copy of Effect. foldkit-durable's Node entry requires Node 22 for node:sqlite; foldkit-durable/core runs on any SQLite client, a browser's included. drizzle-orm is a peer of the Drizzle packages, so the application's copy is the one they use. The release matrix lists every package's current version.

Agent skill

skills/foldkit-plus is an Agent Skill that teaches a coding agent what each package owns, when to reach for it, and a basic example of each. Install it into Claude Code, Cursor, OpenCode, and other agents with skills.sh:

npx skills add doeixd/foldkit-plus --skill foldkit-plus

Go deeper

The root README is the map. The guides teach the architecture and each package README documents its API.

The 0.7 release post introduces Entity, Form, and Crud. The documentation map gives the full reading order, package references, design notes, and historical material. The release matrix tracks published versions.

Status

Foldkit Plus is 0.x, built against a 0.x Foldkit and Effect 4. APIs are still settling and minor releases may break. The CHANGELOG records what changed and why.

The repository is exercised as a system: package tests run in CI, README-facing examples are type-checked or pinned as deterministic transcripts, and pnpm demo runs the worked examples together.

Contributing and releasing

pnpm install
pnpm format:check
pnpm typecheck
pnpm test
pnpm demo

See CONTRIBUTING.md for the full development workflow and AGENTS.md for repository working agreements and documentation standards. Release mechanics and the package/version matrix live in docs/releases.md.

License

MIT. These are community packages, published unscoped as Foldkit itself is. They are not affiliated with or endorsed by the Foldkit maintainers, and the names are theirs for the asking.

References

• Foldkit — https://foldkit.dev/ · https://github.com/foldkit/foldkit
• WebMCP — https://github.com/webmachinelearning/webmcp
• Agent Native — https://github.com/BuilderIO/agent-native