Surface / foldkit-surface

Comparing Optics, Surfaces, and Submodels

Surface complements Effect Optics and Foldkit Submodels at different levels of an application:

ConceptWhat 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:

ts
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:

ts
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.fromOptic to 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

Limits

  • Pure data and static descriptions only: fetching remote rows lives in foldkit-remote, and offline replication lives in foldkit-sync.
  • Model codecs run purely without Effect services.
  • Projections declare dependencies and carry metadata without acting on them; downstream packages such as foldkit-remote interpret their own keys.

Next