Mount

Most Foldkit code is declarative. The view is a pure function from Model to Html. It does not reach into the DOM, hold element references, or run side effects.

Mount is the escape hatch for work whose cause is a particular element existing in the DOM. OnMount supplies the live Element, starts the work when that element enters the DOM, and tears it down when the element leaves.

Use Mount.define for work that produces one Message when it starts. Its execute receives the live element and the rendered view's state, then returns an Effect<Message> that emits that Message. Its scope remains open until unmount so cleanup registered with Effect.acquireRelease runs at the right time. Use Mount.defineStream when listeners or observers on the element must emit a continuing Stream<Message>.

Both forms require at least one declared result Message. When no result needs to change the Model, return a descriptive Completed* Message and leave the Model unchanged in update. The Message keeps the effect visible to DevTools, Scene tests, and replay.

Choose a lifecycle primitive by what causes the work:

• A Command runs because update just handled a Message. Use it for one-time work such as navigation, network requests, storage, analytics, or focusing an input after OpenedDialog.

• A Mount runs because an element exists, and the work needs that live Element. Use it to measure geometry, portal a node, attach an element observer, or instantiate a library in a specific container.

• A Subscription listens to an external event source while dependencies derived from the Model remain active. Timers, document events, system theme changes, and WebSocket messages fit this shape.

• A ManagedResource owns a stateful handle whose lifetime follows a Model condition and whose operations are performed by Commands.

• A CustomElement renders a native web component with declarative properties and CustomEvents. Use Mount only when the foreign element requires an imperative API instead.

A Mount follows the lifetime of a DOM node, not a VNode. Foldkit reconstructs VNodes on every render, but the differ reuses an existing DOM node when its tag and identity still match. A reused node keeps its Mount running. A replaced node closes the old Mount's scope, runs its finalizers, and starts a fresh Mount on the new node.

View-function identity and stable keys keep that lifecycle attached to the right logical element. This matters in mapped lists, where an unkeyed reorder can reuse the same DOM position for different data. Key each item by a stable Model identifier so its DOM node and Mount move together.

Portal-to-body is a small example. When an overlay enters the DOM, its Mount moves the live element to document.body so it can escape clipping ancestors. When the element unmounts, the paired release removes it.

import { Effect } from 'effect'
import { Mount } from 'foldkit'
import type { Html, HtmlBuilder } from 'foldkit/html'
import { defineMessageUnion } from 'foldkit/message'

const Message = defineMessageUnion({
  CompletedPortalToBody: {},
})

// Portal-to-body is a per-instance lifecycle effect that uses the element
// directly. The Effect's acquireRelease moves the element to document.body
// at mount and removes it on unmount. The work is pure DOM manipulation on
// the element Mount provides, idempotent and safe to re-run during
// DevTools time-travel.

const PortalToBody = Mount.define('PortalToBody', {
  messages: [Message.CompletedPortalToBody],
  execute: ({ element }) =>
    Effect.gen(function* () {
      yield* Effect.acquireRelease(
        Effect.sync(() => document.body.appendChild(element)),
        () => Effect.sync(() => element.remove()),
      )
      return Message.CompletedPortalToBody()
    }),
})

const overlayView = (h: HtmlBuilder<Message>): Html =>
  h.div([h.Class('fixed inset-0 bg-black/50'), h.OnMount(PortalToBody())])

A Mount often needs an input that differs by element instance, such as an initial scroll position, chart data, or a stable host id. Declare those under args, using the same Schema record shape a Command takes. args, messages, and execute are all named fields on one config object. execute receives the runtime fields element and viewStateChanges alongside the declared args, so those names are reserved and rejected under args:

Mount.define(name, {
  args: argSchemas,
  messages: [ResultMessage],
  execute: ({ element, ...argValues }) => Effect<Message>,
})

Calling the Definition with an args record creates the MountAction passed to OnMount. That call never runs execute. The runtime calls it when the element enters the DOM, so nothing execute does happens inside the pure view that built the action. Mount.defineStream takes the same fields, and its execute returns a Stream<Message> instead.

Args are only per-instance inputs. Module constants stay in lexical scope, app-wide services come from Foldkit Resources, Model-owned handles come from ManagedResources, and Effect services remain available through yield* inside execute.

When a later Message changes the Model and should trigger new DOM work, return a Command from that Message's update handler. A Subscription is appropriate when a Model dependency controls the lifetime of an external stream or a paired DOM state, or when a browser event must be handled synchronously, such as calling preventDefault inside its listener. Mount args are not reactive properties for either case.

Time travel pauses the rendered view, not the application. The live Model, history, Commands, Subscriptions, and ManagedResources continue normally behind the historical DOM. A Mount owns imperative behavior attached to an element in that rendered view, so its execute input includes viewStateChanges, a Stream<'Live' | 'Paused'>.

The Stream begins with the rendered view state at the moment the Mount is acquired, followed by changes. That initial state is retained while execute performs asynchronous setup, so a Mount inserted by a historical render receives Paused first even if it consumes the Stream only after setup finishes. The Stream stays open for the Mount's lifetime and reports only Live when time travel is unavailable. A surviving live Mount is not restarted, interrupted, or reacquired when the view pauses. On resume, Mounts receive Live only after Foldkit has patched the latest live view back into the DOM.

Custom renderers without time travel can pass Mount.liveViewStateChanges as the required second argument to a low-level MountAction.f call. It emits Live immediately and stays open.

Use the Stream to update state owned by the imperative integration itself. For example, a rich-text editor can call its read-only API while the historical view is installed, then restore editing when the live view returns:

import { Effect, Stream } from 'effect'
import { Mount } from 'foldkit'
import { defineMessageUnion } from 'foldkit/message'

import { Editor } from '@tiptap/core'

const Message = defineMessageUnion({
  CompletedMountEditor: {},
})

const MountEditor = Mount.define('MountEditor', {
  messages: [Message.CompletedMountEditor],
  execute: ({ element, viewStateChanges }) =>
    Effect.gen(function* () {
      const editor = yield* Effect.acquireRelease(
        Effect.sync(() => new Editor({ element })),
        mountedEditor => Effect.sync(() => mountedEditor.destroy()),
      )

      yield* viewStateChanges.pipe(
        Stream.runForEach(viewState =>
          Effect.sync(() => editor.setEditable(viewState === 'Live')),
        ),
        Effect.forkScoped,
      )

      return Message.CompletedMountEditor()
    }),
})

A Mount acquired by the live view keeps participating in the live application while a historical view is displayed. Its asynchronous setup can complete, and its external streams can keep producing Messages. Foldkit cannot tell whether an arbitrary Stream emission came from historical DOM interaction, a timer, an observer, or a network source, so the integration must use viewStateChanges to stop its own DOM-derived interaction while paused. Do not translate this signal into an application Message. It describes which Model the DOM currently represents, not a change to application state.

A Mount acquired by a historical render is different: its Messages cannot reach update, change the live Model, or enter history. If the resumed live view reuses that element and declares a Mount there, Foldkit releases the replay acquisition before starting the live action with the live render's args and dispatch. Cleanup finishes before the replacement setup begins, so the old integration cannot tear down the new handle. Within the live render owner, a surviving Mount follows the latest live Submodel toParentMessage wiring, matching event handlers without ever borrowing a historical render's wiring.

Mount is especially useful when a library owns a rendered subtree. Charts, code editors, map renderers, and force-directed graphs all need a real element to render into and a way to release their resources.

Construct the handle in an acquire Effect, return the Mount's result Message, and register teardown with Effect.acquireRelease. The Effect can finish after emitting its Message because Foldkit keeps its scope open until the element unmounts.

import { Effect, Schema } from 'effect'
import { Mount } from 'foldkit'
import type { Html, HtmlBuilder } from 'foldkit/html'
import { defineMessageUnion } from 'foldkit/message'

const Message = defineMessageUnion({
  SucceededMountChart: {},
  FailedMountChart: { reason: Schema.String },
})

// Mount.define gives the action a name and constrains what Messages it can
// produce, plus an args record so the chart's per-instance data flows through
// declared values rather than a closure. The runtime calls execute with the
// live element on insert, runs the Effect to produce one Message, dispatches
// it, and closes the scope on destroy (firing any acquireRelease finalizers).

const ChartData = Schema.Array(Schema.Number)
type ChartData = typeof ChartData.Type

const MountChart = Mount.define('MountChart', {
  args: { data: ChartData },
  messages: [Message.SucceededMountChart, Message.FailedMountChart],
  execute: ({ element, data }) =>
    Effect.gen(function* () {
      yield* Effect.acquireRelease(
        Effect.tryPromise(() => import('some-chart-library')).pipe(
          Effect.map(({ Chart }) => new Chart(element, { data })),
        ),
        chart => Effect.sync(() => chart.destroy()),
      )
      return Message.SucceededMountChart()
    }).pipe(
      Effect.catch(error =>
        Effect.succeed(
          Message.FailedMountChart({
            reason: error instanceof Error ? error.message : String(error),
          }),
        ),
      ),
    ),
})

const chartView = (data: ChartData, h: HtmlBuilder<Message>): Html =>
  h.div([h.Class('w-[480px] h-[320px]'), h.OnMount(MountChart({ data }))])

The Model owns the input data. The library owns its rendered subtree. Foldkit owns the lifecycle.

When a foreign element already exposes a declarative property-and-event API, bind it with CustomElement instead.