doeixd/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 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
| What you are adding | Authoritative owner | Extension |
| --- | --- | --- |
| Local UI state or a reusable widget | Parent Model and its update/child update | Bundle, Primitives |
| Facts loaded from a server | Server; the client cache is disposable | Remote |
| Offline edits that must converge | Client-authored operations in an authoritative journal order | Sync + Durable |
| Offline edits to rows a server owns | The journal; the table is its read model | Sync (/entity, /journal) + Remote |
| An interactive grid over the application's rows | The grid's Bundle for focus, selection and columns; the rows stay the application's | Data grid |
| A URL or remembered preference | Local Model; the external value is a representation | Mirror |
| Agent access or a customizable view | Existing state and transitions | Agent, Surface, Mixins |
A Surface can observe several owners. Observing a field does not grant a second
package permission to change it outside its owning transition.
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.
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,