Generate a complete Foldkit program based on this description:
$ARGUMENTS
Phase 1: Analyze the Description
Before writing any code, analyze the description to identify:
- Domain entities: nouns that become Model fields (e.g., "todos", "user", "score")
- User interactions: verbs that become Messages (e.g., "add", "delete", "filter", "submit")
- Async operations: external data that becomes Commands (e.g., "fetch weather", "save to localStorage")
- Real-time needs: streaming data that becomes Subscriptions (e.g., "live updates", "countdown", "WebSocket")
- Pages/navigation: URL structure that becomes routes (e.g., "home page", "detail page")
- UI component needs: interactive widgets that map to Foldkit UI components (e.g., "dropdown" → Menu, "modal" → Dialog, "tabs" → Tabs, "autocomplete" → Combobox, "date picker" → DatePicker, "file upload" → FileDrop, "reorderable list" → DragAndDrop, "toast/notification" → Toast, "hover tooltip" → Tooltip, "range/price filter" → Slider, "long scrolling list" → VirtualList)
- Form validation needs: required fields, format checks, async uniqueness →
foldkit/fieldValidationmodule (see Phase 4) - Date handling: birthdays, deadlines, scheduling →
Calendarmodule +DatePickerorCalendarfrom@foldkit/ui - File handling: uploads, attachments, images →
Filemodule +FileDropfrom@foldkit/ui - Remote data: anything fetched, cached, refreshed, or revalidated → the
AsyncDatamodule (see Phase 4). Don't hand-roll a loading/error union - Multi-state flows: a described process that moves through several named steps with rules about which step follows which (checkout, onboarding, multi-step approval, a connection lifecycle) → consider the
Machinemodule (foldkit/experimental). Writing the transitions as a table makes the edge set enumerable, sounreachableStates()anddeadTransitions()catch a missing or unreachable step by computation instead of by review. Raise it as an option in the analysis you present, noting it is underexperimental/, and let the user choose. Plaints()unions with oneM.tagsExhaustiveare still right for a flow of two or three states.repos/foldkit/examples/checkout-machine/is the reference - Host embedding: the program runs inside another app ("a widget in our React app", "embed this in an existing page", "the host needs to control it") →
Runtime.makeElementplus theRuntime.embedlifecycle handle, with Flags for initial data and Ports for ongoing communication in both directions.repos/foldkit/examples/embedding/is the canonical reference: a plain TypeScript host driving a Foldkit widget end to end
Present this analysis to the user before proceeding.
If the description is detailed and unambiguous, summarize the analysis and confirm before moving on. But if there are gaps (unclear state transitions, vague UI requirements, unspecified error handling, missing edge cases, ambiguous domain boundaries, unclear counter/reset semantics), ask targeted clarifying questions before proceeding. Don't ask open-ended questions like "anything else?". Ask specific questions about the gaps you found.
UX/behavior gaps:
- "Should the todo list persist across page reloads (localStorage), or start fresh each session?"
- "When the API call fails, should the app show an inline error or a dialog?"
- "You mentioned 'users can edit items'. Is that inline editing or a separate edit page?"
Domain-logic gaps (easy to miss, expensive to fix):
- "When the user skips an interval, does that count as 'completed' for purposes of the streak?"
- "Does a counter that tracks 'completed' increments on successful actions only, or on skipped actions too?"
- "If the user triggers a reset mid-flow, does the counter reset with it, or persist across resets?"
- "You mentioned 'after N events, trigger X'. Is that N events total, or N events since the last X?"
- "On the Nth action in a cycle, which action does it trigger, the cycle's first or last?"
Domain-logic questions often surface off-by-one bugs before they hit the code. If the description has any counter, cycle, streak, or "after N" phrase, ask about edge cases at 0 and 1 and N specifically.
The goal is to resolve ambiguity early so the generated code matches what the user actually wants, not what you assumed.
Phase 2: Study Reference Examples
Resolve the Foldkit repository
Resolve the Foldkit repository root before following any repository path in this skill:
- In OpenCode, use the
@foldkitproject reference first when it is available. Its local path is advertised in the session's project references. Do not ask the user to vendor Foldkit when this reference is available. - Otherwise use the project's
repos/foldkit/subtree when present. - When working inside Foldkit itself, use the project root.
Repository paths such as examples/weather/src/main.ts, packages/website/src/, and legacy paths beginning with repos/foldkit/ are relative to that resolved root; strip the repos/foldkit/ prefix when necessary. Paths such as architecture.md are relative to this skill directory.
Read the architecture and conventions guides to internalize the rules:
- Architecture guide: TEA structure, file organization, type patterns
- Conventions guide: naming, Effect-TS patterns, anti-patterns
- Verification checklist: not just for Phase 5, also the generation bar. Skim the Quality Bar section now so you generate code that already meets it rather than code that will fail review.
- Blind spots: what the Phase 6 reviewer will grade you against. Reading it now is cheaper than fixing it later.
These four files are a snapshot of a moving codebase. When they disagree with the resolved Foldkit repository or the .d.ts in node_modules, the live source is right. Treat the disagreement as a bug in this skill and say so in your final report.
If you have access to a context7 MCP tool, use it to look up Effect-TS documentation when you're unsure about an API. Effect is a large library. Verify function signatures rather than guessing.
Quality exemplars
Two codebases are the quality bar for generated apps. Not just "patterns to copy" but "the level of craft to match":
packages/typing-game/client/src/: production multi-page app: Submodels, OutMessage, update/view decomposition, curried handler extraction, subscription patterns, domain modules.packages/website/src/: production Foldkit website: page organization, shared view primitives, route-driven rendering, idiomatic domain separation.
Before generating, spot-check at least ONE file from each (the shape of update.ts / how handlers get extracted / how domain files are structured) and match that level of craft in your output. The generated code should be indistinguishable from hand-written exemplar code.
Then read the tier-specific example files that match the app's complexity. Always read at least one tier-specific example. Never generate from memory alone.
Complexity tiers
Tier 1: Single page, no async, minimal state:
Read examples/counter/src/main.ts
Tier 2: Timers, subscriptions, simple stateful apps:
Read examples/stopwatch/src/main.ts (timer via subscription, Duration field pattern) and examples/todo/src/main.ts (CRUD with localStorage via flags)
Tier 3: Async operations, loading/error states, API calls, form validation:
Read examples/weather/src/main.ts (HTTP with HttpClient) and examples/form/src/main.ts (uses foldkit/fieldValidation; see the Form Validation section in Phase 4)
Tier 4: URL routing, multiple pages, query parameters:
Read examples/routing/src/main.ts and examples/query-sync/src/main.ts
Tier 5: Complex state, nested domain models, CRUD, drag-and-drop:
Read examples/shopping-cart/src/main.ts (nested domain schemas, cart state) and examples/kanban/src/main.ts (CRUD with DragAndDrop, flags restoring from localStorage, subscriptions)
Tier 6: Submodels, OutMessage, multi-step forms, auth flows, multi-module apps:
Read examples/auth/src/main.ts (login/signup with Submodels, OutMessage, protected routes) and examples/job-application/src/main.ts (multi-step form with deeply nested Submodels in step/, DatePicker, FileDrop, Listbox, Calendar module for date handling)
Tier 7: Real-time, WebSocket, Managed Resources, production-grade:
Read packages/typing-game/client/src/update.ts, then explore its page/home/ and page/room/ directories for the full Submodel/OutMessage pattern.
Read examples from the target tier AND all lower tiers. A Tier 4 app should reflect patterns from Tiers 1-3 as well.
Phase 2.5: Identify Foldkit UI Component Opportunities
Foldkit ships accessible UI components that handle keyboard navigation, ARIA attributes, and focus management automatically. They live in a separate package, @foldkit/ui, and are imported by name:
import { Button, Dialog, Input } from "@foldkit/ui"
There is no Ui namespace on the foldkit package. Reach for Dialog.view, not Ui.Dialog.view. Deep imports (@foldkit/ui/dialog) work too when you want to keep the barrel out of the bundle.
Before generating, check if any part of the app maps to a built-in component:
| User Need | Component | What you get for free |
|---|---|---|
| Modal/dialog/confirmation | Dialog |
Focus trapping, Escape to close, scroll locking, backdrop |
| Tabbed content | Tabs |
Arrow key navigation, aria-selected, roving tabindex |
| Dropdown menu | Menu |
Arrow keys, typeahead search, aria-expanded, click-outside |
| Autocomplete/tag input | Combobox |
Filtering, arrow key selection, aria-activedescendant |
| Select dropdown | Select |
Keyboard selection, aria-selected, positioning |
| Single selection from options | RadioGroup |
Arrow key cycling, aria-checked |
| On/off toggle | Switch |
Spacebar toggle, aria-checked |
| Boolean option | Checkbox |
Spacebar toggle, aria-checked, indeterminate |
| Expandable section | Disclosure |
Enter/Space toggle, aria-expanded |
| Floating content on hover/click | Popover |
Positioning, click-outside, focus management |
| Hover tooltip | Tooltip |
Show-delay, keyboard dismiss, positioning, aria-describedby |
| Single-select list | Listbox |
Arrow keys, typeahead, aria-selected |
| Text input | Input |
Consistent styling/behavior wrapper |
| Multi-line text | Textarea |
Auto-resize, consistent styling |
| Form group | Fieldset |
Disabled state propagation, grouping |
| Styled button | Button |
Consistent click/keyboard handling |
| Inline calendar grid | Calendar |
Month navigation, keyboard nav, aria-selected, date constraints |
| Date input + popover | DatePicker |
Calendar popover, input masking, keyboard nav, constraints |
| File upload zone | FileDrop |
Drag-and-drop, click-to-browse, accept filters, validation |
| Reorderable list | DragAndDrop |
Pointer + keyboard drag, drop zones, announcement region |
| Transient notifications | Toast |
Auto-dismiss, pause-on-hover, stacking, role=status/alert |
| Numeric range / price filter | Slider |
Arrow/Home/End keys, aria-valuenow, multi-thumb ranges |
| Long scrolling list | VirtualList |
Windowed rendering, scroll anchoring, measured item heights |
| Site/section navigation | Nav |
Current-page marking, keyboard traversal, landmark semantics |
The package is not one shape.
Stateful Submodels carry their own Model, Message, update, and (mostly) OutMessage, and are embedded via h.submodel: Menu, Listbox, Combobox, Calendar, DatePicker, Dialog, Popover, Tabs, Tooltip, FileDrop, DragAndDrop, Slider, VirtualList, plus Toast once built through Toast.make(PayloadSchema).
Stateless render helpers have no Model at all. You call view directly and store the value in your own Model: Button, Input, Textarea, Select, Fieldset, Checkbox, Switch, Disclosure, RadioGroup, Nav.
Don't take that split on faith, because components have moved across it (Checkbox, Switch, and Disclosure became controlled render helpers; Tabs and Slider moved their selection to the parent Model). Read the component's public.d.ts: exporting Model and update means Submodel, exporting only view and a ViewConfig / ViewInputs type means render helper. A render helper does not want a Got* Message.
To use a stateful Submodel:
- Add its Model to your Model:
confirmDialog: Dialog.Model - Add a
Got*Message:GotConfirmDialogMessagewith{ message: Dialog.Message } - Initialize in init:
confirmDialog: Dialog.init({ id: 'confirm-dialog' }) - Delegate in update:
GotConfirmDialogMessage: ({ message }) => ... - Embed in view via
h.submodel:h.submodel({ slotId: 'confirm-dialog', view: Dialog.view, model: model.confirmDialog, toParentMessage: message => GotConfirmDialogMessage({ message }) })(addviewInputsfor components whose view takes them)
Always prefer Foldkit UI components over hand-rolling interactive widgets. They make accessibility the default, not an afterthought.
For form inputs specifically: every text input, textarea, and button in a form MUST go through Input, Textarea, and Button. This is not optional, even though raw input/textarea HTML elements are available from html<Message>(). The form example (examples/form/src/main.ts) defines inputFieldView and textareaFieldView helpers that wrap Input.view and Textarea.view with label + validation feedback. Copy that helper pattern. Raw input/textarea are for non-form cases (search fields, inline editors) where you're intentionally working below the component layer, and even then, reach for the component first.
If the app uses UI components, always read the ui-showcase example first to understand how components are wired. This is the canonical reference for Foldkit UI integration patterns:
examples/ui-showcase/src/main.ts: root wiring,Got*delegation,toParentMessagehelpersexamples/ui-showcase/src/ui/message.ts: how component Messages are structuredexamples/ui-showcase/src/ui/model.ts: how component Models are composedexamples/ui-showcase/src/ui/update.ts: how component updates are delegatedexamples/ui-showcase/src/ui/subscriptions.ts: which components need Subscriptions lifted into the parent (DragAndDrop,Slider,VirtualList)examples/ui-showcase/src/ui/toast.ts: read when usingToast. It's unique in that it's parameterized on a payload schema viaToast.make(PayloadSchema), returning a typed module you import from
Directory names under examples/ui-showcase/src/ have moved before. List the directory rather than trusting these paths blind.
For apps using DatePicker, FileDrop, or other recently-added components, also read the job-application example (see Tier 6 below). It's the most complete real-world integration of these components together.
Phase 3: Determine File Organization
Match the file structure to the app's complexity. The architecture stays the same at every scale; only the file organization changes.
What lives in which file
Beyond the tier-based layouts below, follow these "schema placement" rules to avoid model.ts bloat:
model.tsholds theModelschema + any schemas that are fields of Model (or composed into fields, like form state / submit state unions). Nothing else.command.tsholds schemas for the payloads commands send to / receive from external systems, in particular the persistence schema thatsaveStateserializes andflagsdeserializes. The persistence schema is a command-layer concern, not a model concern; it often looks like a subset of Model but it isn't part of Model.domain/*.tsholds domain entity schemas and pure operations on them.message.tsholds messages (only).route.tsholds route variants + router pipelines.
A common mistake (because kanban colocates SavedBoard in model.ts): putting the persistence schema in model.ts because "it's schema." It's schema for the persistence layer, not for the Model. Move it to where it's used.
Single file (Tier 1-2, under ~300 lines):
src/main.ts ← Model, Message, init, update, view
src/entry.ts ← Runtime.makeApplication + Runtime.run
Split commands + messages (Tier 3, has async operations):
src/main.ts ← Model, init, update, view
src/entry.ts ← Runtime.makeApplication + Runtime.run
src/message.ts ← Message definitions
src/command.ts ← Command functions
Important rule: if you extract command.ts, you MUST also extract message.ts. Commands reference Message constructors (e.g. SucceededFetchWeather({...})) as their Effect return values. If Messages live in main.ts and Commands live in command.ts, command.ts imports from main.ts and main.ts uses Commands from command.ts, a circular import. Pull Messages out first, then both main.ts and command.ts import from message.ts.
Full split (Tier 4-5, multiple concerns):
src/main.ts ← init, update, view
src/entry.ts ← Runtime.makeApplication + Runtime.run
src/model.ts ← Model schema
src/message.ts ← Message definitions
src/command.ts ← Command functions
src/route.ts ← Route parser (if routing)
src/view.ts ← View functions (if view is large)
src/domain/ ← Shared domain schemas (if multiple entities)
Submodel directories (Tier 6-7, independent modules):
src/main.ts ← Root init, update, view
src/entry.ts ← Runtime.makeApplication + Runtime.run
src/model.ts ← Root model (contains submodels)
src/message.ts ← Root messages + Got* bridging
src/command.ts ← Shared commands
src/route.ts ← Route parser
src/domain/ ← Shared domain schemas
src/page/
featureA/
main.ts ← Submodel init, update, view
message.ts ← Submodel messages + OutMessage
command.ts ← Submodel commands
featureB/
...
Phase 3.3: Architecture sketch (Tier 4+ only)
For Tier 4+ apps (routing, domain modules, multiple entities, submodels) produce a compact sketch BEFORE generating implementations. Tier 1-3 apps are small enough to generate in one pass; Tier 4+ apps burn a lot of effort if the structure is wrong.
The sketch has five parts. Emit them inline in the conversation, get confirmation, THEN scaffold:
- File tree: the exact paths you will create. Match Phase 3's organization.
- Model shape: the top-level
S.Structfields and their types. Not the full schema, just the shape. - Message list: every Message you plan to define, grouped by category (clicks, inputs, commands, out-messages).
- Route list: if routing, every
r('...', {...})with params and the path each maps to. - Domain operations: for each file in
domain/, the operations it will expose (Link.byNewest,Link.filterByTag, etc.).
Example for a Tier 4 link saver:
### Sketch
Files:
src/main.ts, entry.ts, model.ts, message.ts, command.ts, route.ts
src/domain/link.ts, index.ts
src/story.test.ts, scene.test.ts
Model:
route: AppRoute
links: ReadonlyArray<Link>
newLinkForm: NewLinkForm (url: Field<string>, title/description/tagsInput: string, submitState)
Messages:
Clicks: ClickedSaveLink, ClickedDeleteLink
Inputs: UpdatedLinkUrl, UpdatedLinkTitle, UpdatedLinkDescription, UpdatedLinkTagsInput, BlurredLinkUrl
Commands: SubmittedNewLinkForm, SucceededSaveLinks, FailedSaveLinks
Routing: ClickedLink, ChangedUrl, CompletedNavigateInternal, CompletedLoadExternal
Toggles: ToggledFavorite
Routes:
HomeRoute → /
NewLinkRoute → /new
TagFilterRoute → /tag/:tag
NotFoundRoute → /* fallback
Domain:
Link: schema + byNewest, filterByTag, toggleFavorite, remove, updateById
After emitting the sketch, ask the user to confirm or adjust. Don't start scaffolding or generation until they do. If the user confirms silently (e.g. "looks good, continue"), proceed. If they adjust, iterate on the sketch. Don't write code against a version they haven't approved.
This step is frequently tempting to skip because the agent "knows what it's doing." Skip it and you ship a fully-generated app that turns out to need structural changes. That's the expensive form of iteration. The sketch is the cheap form.
Phase 3.5: Scaffold the Project
Before generating code, scaffold a runnable project using create-foldkit-app:
npx create-foldkit-app@latest
Run with no flags to drop into the interactive prompts; pick the counter example as the base (simplest starting point) and the user's preferred package manager. The generated project includes:
package.jsonwith all Foldkit and Effect dependenciesvite.config.tswith Tailwind and the Foldkit Vite plugintsconfig.jsonwith strict TypeScript settingsindex.htmlwith the root containersrc/styles.csswith Tailwind importAGENTS.mdwith Foldkit conventions
Ensure future Foldkit repository access
If OpenCode's @foldkit project reference is available, repository access is already configured. Do not offer or add a subtree.
Otherwise, offer to vendor Foldkit as a git subtree so future AI sessions can reference the full source, examples, and docs directly from the user's project. Commit the scaffold first so subtree has a base commit to merge into:
git init # if not already a git repo
git add .
git commit -m "chore: initial commit"
git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git main --squash
This fallback is optional but strongly recommended when no managed repository reference exists. The scaffolded AGENTS.md includes a subtree_prompted: false line that agents check on future sessions. If the subtree is absent and this flag is false, the agent offers to add it. Handling it up front here means the user's next AI session already has full context. If the user declines, update the line to subtree_prompted: true so they aren't asked again.
To refresh the subtree later: git subtree pull --prefix=repos/foldkit https://github.com/foldkit/foldkit.git main --squash.
Replace the scaffold
Then replace the counter example code in src/main.ts (and add additional source files as needed) with the generated app code.
Phase 3.7: Ground the Foldkit APIs
Before writing any code, READ the type signatures of every Foldkit module you will use. Guessing signatures wastes cycles: each wrong guess is a tsc error, a re-read, an edit, another typecheck. Five minutes of reading prevents thirty minutes of iteration.
The exact files to read
For each Foldkit module you plan to use, read the .d.ts at the paths below. Read the public surface; you don't need the internals. Write a short signature crib in your working notes so you don't have to re-check while generating.
# Every app
<project>/node_modules/foldkit/dist/index.d.ts # top-level re-exports: the authoritative list of what `foldkit` exposes
<project>/node_modules/foldkit/dist/html/index.d.ts # html<Message>(), element signatures, Attribute<Message>
<project>/node_modules/foldkit/dist/message/index.d.ts # m()
<project>/node_modules/foldkit/dist/schema/index.d.ts # ts(), r()
<project>/node_modules/foldkit/dist/struct/index.d.ts # evo(): check nested-update signature
<project>/node_modules/foldkit/dist/update/public.d.ts # Update.Return, Update.ReturnWithOutMessage, Update.combine, Update.refresh
<project>/node_modules/foldkit/dist/runtime/runtime.d.ts # ApplicationInit, RoutingApplicationInit, makeApplication, makeElement
# If using routing
<project>/node_modules/foldkit/dist/route/parser.d.ts # literal, slash, string, int, Route.root, Route.mapTo, Route.oneOf, Route.parseUrlWithFallback
<project>/node_modules/foldkit/dist/url/index.d.ts # toString
<project>/node_modules/foldkit/dist/navigation/index.d.ts # pushUrl, load: all return Effect<void> (no Effect.ignore needed)
# If using async / side effects
<project>/node_modules/foldkit/dist/command/index.d.ts # Command.define: result schemas are required. Command.mapMessages for parent<-child mapping
<project>/node_modules/foldkit/dist/asyncData/public.d.ts # AsyncData: Idle/Loading/Refreshing/Failure/Stale/Success + Schema, match, isPending, hasData, revalidate
<project>/node_modules/foldkit/dist/http/public.d.ts # Http.layer: provide it to Commands that use HttpClient
<project>/node_modules/foldkit/dist/dom/index.d.ts # focus, advanceFocus, scrollIntoView, showDialog, closeDialog, clickElement, lockScroll, unlockScroll, inertOthers, restoreInert, detectElementMovement, waitForAnimationSettled. For time/random/uuid/delay use Effect's Clock, Random, Effect.uuid, Effect.sleep + Duration directly.
# If using subscriptions
<project>/node_modules/foldkit/dist/subscription/index.d.ts # Subscription.make<Model, Message>, Subscription.lift, Subscription.aggregate
# If using mount / managed-resource / custom-element
<project>/node_modules/foldkit/dist/mount/public.d.ts # Mount.define (one-shot) / Mount.defineStream (continuous): per-instance VNode lifecycle
<project>/node_modules/foldkit/dist/managedResource/public.d.ts # ManagedResource.make / lift / aggregate + tag: for stateful runtime objects keyed on Model condition
<project>/node_modules/foldkit/dist/customElement/index.d.ts # CustomElement.define: for typed bindings to native web components
# If the host application drives the program
<project>/node_modules/foldkit/dist/port/public.d.ts # Port.inbound / outbound / emit / stream / subscription
# If using forms
<project>/node_modules/foldkit/dist/fieldValidation/public.d.ts # Field (tagged union), makeRules({required?, rules}), validate, allValid; rule constructors on the Rule namespace (Rule.url(options), Rule.email, Rule.minLength, Rule.pattern, Rule.fromSchema, ...)
# Rule.Rule is [Predicate, Rule.RuleMessage], NOT {test, message}. Field.Invalid has `errors: NonEmptyArray<string>`, not `error: string`.
# If using any UI component (SEPARATE PACKAGE)
<project>/node_modules/@foldkit/ui/dist/<component>/public.d.ts # Model, Message, init, update, view (Submodel-shaped) or ViewConfig (render-helper-shaped), OutMessage when applicable
# Check: is it a Submodel (Menu/Listbox/Combobox/Calendar/DatePicker/Dialog/Popover/Tabs/Tooltip/FileDrop/DragAndDrop/Slider/VirtualList/Toast) embedded via h.submodel, or a stateless render helper (Button/Input/Textarea/Select/Fieldset/Checkbox/Switch/Disclosure/RadioGroup/Nav) called directly? Submodels carry their own Model/Message/update/OutMessage; render helpers don't. Check ViewInputs (for Submodels) or ViewConfig (for helpers) for the slot callbacks (toView, itemToConfig, etc.).
# If using dates
<project>/node_modules/foldkit/dist/calendar/index.d.ts # CalendarDate, today.local (returns Effect<CalendarDate>); for raw millis use Clock.currentTimeMillis
If a path above doesn't resolve, list the package's dist/ and find the module. The .d.ts is authoritative and this file is not. Where the two disagree, the .d.ts is right and the disagreement is a bug in this skill worth reporting.
What to record in the crib
For each symbol you'll call, write one line:
html<Message>(): { div, input (VOID), textarea, button, Class, Href, For, Id, Role, OnClick(Message), OnInput(value=>Message), OnBlur(Message), OnSubmit(Message), keyed, empty, submodel, ... }
Route.mapTo(schema)(parser): curried
pushUrl(path): Effect<void> // NOT fallible, no Effect.ignore needed
urlToString(url: Url): string
Update.Return<Model, Message>: readonly [Model, ReadonlyArray<Command<Message>>]
Command.mapMessages(commands, toParentMessage): re-tag a child's Commands
AsyncData.Schema(DataSchema, ErrorSchema): { schema, Idle(), Loading(), Success({data}), Failure({error}), ... }
AsyncData.match(value, { onIdle, onLoading, onRefreshing, onFailure, onStale, onSuccess })
// handlers take BARE values, except onStale:
// onIdle: () => B onLoading: () => B
// onRefreshing: (data) => B onSuccess: (data) => B
// onFailure: (error) => B onStale: ({ error, data }) => B
Command.define(name, argsSchema, Ok, Err)(({ id }) => Effect): the Effect factory
binds at DEFINITION and receives the decoded args object directly, so you
destructure the fields themselves; the call site passes args:
const Fetch = Command.define('Fetch', { id: S.String }, Ok, Err)(({ id }) => ...)
update: [Fetch({ id })] // NOT Fetch({ id })(effect)
Document: NOT generic, and `body` is a single Html, not an array
Input.view({ id, value, onInput, isInvalid?, type?, placeholder?, toView: (attrs) => Html })
// from '@foldkit/ui', NOT Ui.Input
// attrs: { label: ReadonlyArray<Attribute<M>>, input: ..., description: ... }
Field (schema): NotValidated | Validating | Valid | Invalid(errors: NonEmpty<Rule Message>)
Specific API pitfalls the generator hits repeatedly
Record these in the crib and keep them visible while generating:
inputandbrand other void elements take ONLY attributes:input([...]), neverinput([...], []).textareaandbuttonDO take children.UrlRequesttags areInternalandExternal, notInternalUrl/ExternalUrl.OnClickandOnSubmittake a Message directly, not a() => Message. OnlyOnInputtakes(value) => Messagebecause it needs the input value.keyed,emptyare properties on the record returned byhtml<Message>(): accessed ash.keyedandh.emptyafterconst h = html<Message>(). They are not top-level exports offoldkit/html.- Attribute helpers are specific:
Value(...),Type(...),Placeholder(...),Href(...),Target(...),Rel(...),Rows(n),Id(...),For(...),Role(...),AriaLabel(...). There is no genericAttr('...', '...'). ApplicationInit<Model, Message, Flags>has no URL parameter. For routed apps, useRoutingApplicationInit<Model, Message, Flags>: the second arg isurl: Url.Route.mapTotakes the route schema, not a factory function.pipe(literal('new'), Route.mapTo(NewLinkRoute)). NOTRoute.mapTo(() => NewLinkRoute()).Effect.ignoreis ONLY for fallible Effects.pushUrl(path).pipe(Effect.as(Message())). NoEffect.ignorebecausepushUrlreturnsEffect<void>.Command.definerequires result Message schemas after the name:Command.define('Fetch', SucceededFetch, FailedFetch). Infallible Commands only need one result:Command.define('ReadClock', RecordedTime).makeRulestakes{ required?: Rule.RuleMessage, rules: Array<Rule.Rule> }whereRule.Rule = [Predicate, Rule.RuleMessage]: a tuple, NOT{ test, message }. Rule constructors live on theRulenamespace (Rule.url({ message }),Rule.email(message?),Rule.minLength(n, message?),Rule.pattern(regex, message?),Rule.fromSchema(schema, message)).Field.Invalidhaserrors: NonEmptyArray<string>, noterror: string. UseArray.headNonEmpty(errors)to get the first message; useRule.resolveMessage(message, value)to resolve a rule message to its final string.- Route variants are
HomeRoute,NewLinkRoute, etc., with theRoutesuffix. Every exemplar uses this convention. - Routers are callable for printing:
homeRouter()returns'/',tagFilterRouter({ tag: 'foo' })returns'/tag/foo'. Never hand-construct URLs. - UI components come from
@foldkit/ui, not from aUinamespace onfoldkit.import { Dialog, Input } from '@foldkit/ui', thenDialog.view(...). There is noUiexport on thefoldkitpackage. HttpClientandHttpClientRequestcome fromeffect/unstable/http, not@effect/platform. Provide the client to the Command's Effect withEffect.provide(effect, Http.layer), whereHttpis imported fromfoldkit.@effect/platform-browseris a different thing, used forBrowserKeyValueStoreandBrowserCrypto.- Map a child Submodel's Commands with
Command.mapMessages(childCommands, message => GotChildMessage({ message })). NotCommand.mapEffect. - Name the update return type once per file, and prefer
Update.Return<Model, Message>fromfoldkit/updatefor the alias. Spelling the tuple out by hand is what most examples still do and is fine; what to avoid is skipping the alias and repeatingreadonly [Model, ReadonlyArray<Command.Command<Message>>]at the signature and again insideM.withReturnType<...>(). - Branch on a Model array with
Array.match, not the predicates.Array.isArrayEmptyandArray.isArrayNonEmpty(note the names: notisEmptyArray/isNonEmptyArray) take a mutableArray<A>, so neither compiles against theReadonlyArrayanS.Array(...)field decodes to.Array.matchtakesReadonlyArrayand is what the exemplars use. emptyandkeyedare properties onh, so they are never in thefoldkit/htmlimport list. Import{ Document, Html, html }and reach forh.empty/h.keyed.
Phase 4: Generate the App
Generate files following the architecture and conventions guides exactly. Write all source files into the scaffolded project's src/ directory. For each file, follow these rules:
Model
- Define as
S.Structwith Effect Schema types - Use discriminated unions for state:
Idle | Loading | Error | Ok, never booleans for multi-valued state - Use
Optionfor fields that may be absent. Never empty strings or null - Prefix Option-typed fields with
maybe:maybeCurrentUser,maybeError - For remote data, use the
AsyncDatamodule rather than hand-rolling a union.AsyncData.Schema(WeatherData, S.String)returns{ schema, Idle, Loading, Refreshing, Failure, Stale, Success }; putschemain the Model and build values with the constructors. TheRefreshingandStalestates are the point: they let a reload keep the current data on screen, and a failed reload keep it rather than discarding it.repos/foldkit/examples/weather/src/main.tsis the canonical use. ReadAsyncData.match's signature before calling it: the handlers take bare values (onSuccess: data => ...,onFailure: error => ...), exceptonStale, which takes{ error, data } - For non-remote multi-valued state (form steps, editor modes, connection phases), define variants with
ts()and compose into anS.Union. See Discriminated Unions for State in conventions.md - For apps with multiple domain entities referenced across modules, extract shared schemas into
src/domain/(e.g.,domain/product.ts,domain/session.ts). See the shopping-cart and auth examples for this pattern, and readpackages/website/src/page/projectOrganization.tsfor guidance on when and how to structure domain modules
Messages
Follow the four-group layout strictly:
// Group 1: All m() declarations, no blank lines between them
const ClickedSubmit = m("ClickedSubmit")
const UpdatedEmail = m("UpdatedEmail", { value: S.String })
const SucceededLogin = m("SucceededLogin", { user: User })
const FailedLogin = m("FailedLogin", { error: S.String })
const CompletedFocusInput = m("CompletedFocusInput")
// Group 2: Union + type (no blank line between them)
const Message = S.Union([
ClickedSubmit,
UpdatedEmail,
SucceededLogin,
FailedLogin,
CompletedFocusInput,
])
type Message = typeof Message.Type
Name messages by category:
Clicked*: button/link clicksUpdated*: input value changes (with{ value: S.String }) and external state updates from subscriptions (UpdatedRoom,UpdatedPlayerProgress)Submitted*: form submissionsSucceeded*/Failed*: paired, for commands that can meaningfully failCompleted*: fire-and-forget (verb+object:CompletedFocusInput)Got*: child module results via OutMessage patternLoaded*: data restored from storagePressed*: keyboard inputBlurred*: focus lossSelected*: choice made from a listToggled*: binary state flip
Every message must carry meaning. No NoOp.
Flags (if the initial Model needs side effects)
- Define a
FlagsSchema for data the initial Model needs from side effects - Define
flagsas anEffect<Flags>that computes the values (localStorage reads, current time, etc.) - Pass the result into init. Never perform side effects at module level or inside init directly
- See the flags section in architecture.md for the full pattern
Init
- Return
[Model, ReadonlyArray<Command<Message>>] - If flags are used, accept them as the first parameter:
(flags: Flags) => [Model, Commands]or(flags: Flags, url: Url) => [Model, Commands] - Include startup Commands (initial fetch, focus first input, etc.)
- Use callable Schema constructors for the initial Model:
Model({ field: value })
Update
Name the return type once per file from the framework's alias, then bind the matcher to it:
type UpdateReturn = Update.Return<Model, Message> const withUpdateReturn = M.withReturnType<UpdateReturn>()Update.ReturnWithOutMessage<Model, Message, OutMessage>is the Submodel counterpart.Update.Returnis the preferred spelling; a hand-written tuple alias is what most examples still use and is fine. What to avoid is skipping the alias and repeating the tuple at the signature and again insideM.withReturnType<...>()Use
M.value(message).pipe(withUpdateReturn, M.tagsExhaustive({...})). Never switchUse
evo(model, { field: () => newValue })for immutable updatesWhen a
Succeeded*handler has to write several caches and kick off refetches, sequence them withUpdate.combine(model, [step, step, ...])and build the refetch steps withUpdate.refresh({ read, revalidate, write, load }), which reloads a cache only when it actually holds data.examples/route-transitions/src/main.tsshows bothIn
evo, use point-free field transformers when the update only depends on that field's current value:items: Array.map(updateItem),count: Number.increment,priceSlider: Slider.reflectRange({ min: minPrice, max: maxPrice }). Use() => valuefor replacement values from Messages, child updates, Commands, or other Model fields.Extract complex handlers to separate functions when a case exceeds ~15 lines
For Submodels: return
[Model, ReadonlyArray<Command<Message>>, Option.Option<OutMessage>]See the OutMessage pattern in architecture.md. Child modules signal to parents via
Option.some(OutMessage), parents handle withGot*Messages andM.tagsExhaustive
Commands
- Define Command identities with
Command.define, passing result Message schemas after the name. Result types are required. With an args schema the shape is `Command.define('Fetch', { id: S.String
…(truncated)
