Surface / foldkit-surface
Comparing Optics, Surfaces, and Submodels
Surface complements Effect Optics and Foldkit Submodels at different levels of an application:
| Concept | What it answers |
|---|---|
| Effect Optic | "How do I focus, read, or replace this value inside another value?" |
ModelRef / Projection | "What application data is this focus or derived value made from?" |
| Surface | "What may this feature observe, and which application Messages may it cause?" |
| Foldkit Submodel | "Which state machine owns this state and these transitions?" |
They compose rather than replace one another: modifyFields performs application transitions inside update, an Optic or ModelRef locates a value structurally, a Projection reads or writes a known Model slice, a Surface pairs observation with allowed Messages, and a Submodel owns a state machine boundary:
import { modifyFields } from 'foldkit/struct'
// application transition
modifyFields(model, { todos: () => [] })
// structural addressing
ModelRef.focus(App.model.todos).get(model)
// infrastructure installation
ModelRef.focus(App.model.todos).set(model, restoredTodos)Surface builds on Optics rather than replacing them
Every ModelRef wraps an Effect Optic.Optional. Surface layers Schema validation, dependency paths, application owner identity, get/set accessors, and opaque Metadata onto that optic to form Projection, and adds a name, optional params, and allowed Messages to form Surface. Use ModelRef.fromOptic when you already have an Effect optic and want it to carry Surface dependency and owner metadata.
Surface and Submodels solve different decompositions
- Submodels partition an application by transition ownership: each child owns its own
Model,Message,update,view, and Commands. - Surfaces partition an application by consumer needs: each Surface declares what an existing screen, agent, or subsystem observes and which
Messages it may send, without introducing a new state machine.
Because observation is separate from ownership, one Surface can read across multiple Submodels—such as reading a parent route, a Settings theme, and a Session user together on an account page:
const Model = Schema.Struct({
route: Route,
settings: Settings.Model,
session: Session.Model,
})
const App = Surface.application({ Model, Message })
const AccountPage = App.surface('AccountPage', {
model: ({ model }) => ({
route: model.route, // parent-owned
theme: model.settings.theme, // Settings Submodel
user: model.session.user, // Session Submodel
}),
})Reading model.settings.theme through a ModelRef keeps ownership inside Settings. Any transition to Settings state still goes through the root Message routed to Settings's update (Update.foldChild), rather than writing directly through a setter. Similarly, h.submodel remains the runtime boundary that mounts child views and routes child Messages.
Which one should I reach for?
- Focus or update nested immutable data: use an Effect Optic (or
ModelRef.fromOpticto participate in Surface metadata). - Own private state, update logic, or Commands: use a Foldkit Submodel.
- Declare what a feature reads and which Messages it may send: use a Surface.
- Read across multiple Submodels for one screen: build one Surface over those fields instead of creating a new Submodel to aggregate them.
Ownership and responsibilities
- Reference-based
Modelselection (App.model,Projection.pick,Projection.compose). - Pure
Projectionvalues with codecs, readers, dependency paths, and opaqueMetadata.keyslots. - Application scopes (
Surface.application) with owner identity tokens. - Typed
Messagesubsets (MessageSet.make,MessageSet.union) and validatedActioncapabilities (Action.define,Action.run). - Closure checks (
Closure.reads,Closure.violations) and the law/evidence graph (Contract.laws,Graph.of,Graph.validate,Graph.breakersOf,Graph.toMarkdown,Graph.toMermaid). - Named Surfaces, view bindings, and the shared
Diagnosticschannel.
Limits
- Pure data and static descriptions only: fetching remote rows lives in
foldkit-remote, and offline replication lives infoldkit-sync. Modelcodecs run purely without Effect services.- Projections declare dependencies and carry metadata without acting on them; downstream packages such as
foldkit-remoteinterpret their own keys.
Next
- Fetch server-derived slices declared on Surfaces:
foldkit-remoteand Server-derived state. - Replicate a closed slice offline across devices:
foldkit-sync. - Expose Actions and Surfaces to an AI agent:
foldkit-agent.