create-foldkit-app 0.7.0 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,8 +15,8 @@
     "@effect/platform-node": "4.0.0-beta.59",
     "chalk": "^5.6.2",
     "effect": "4.0.0-beta.59",
-    "rimraf": "^6.1.2",
-    "typescript": "^6.0.2"
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.3"
   },
   "keywords": [
     "create-foldkit-app",

package/templates/base/AGENTS.md

@@ -49,13 +49,23 @@ Don't add type annotations to `evo` callbacks when the type can be inferred.
 
 ### View
 
-Call `html<Message>()` once in a dedicated `html.ts` file and import the destructured helpers everywhere else:
+Bind the `html` factory once per module by calling `html<Message>()`, then reach for `h.div`, `h.OnClick`, and the rest off the returned record. Each view module binds its own `h` against the Message type it dispatches:
 
 ```ts
-// html.ts
-export const { div, button, span, Class, OnClick } = html<Message>()
+const h = html<Message>()
+
+export const view = (model: Model): Html =>
+  h.div(
+    [h.Class('flex flex-col gap-2')],
+    [
+      h.h1([], [`Hello, ${model.name}`]),
+      h.button([h.OnClick(ClickedRefresh())], ['Refresh']),
+    ],
+  )
 ```
 
+For child views that should be agnostic to their parent, take `ParentMessage` as a function generic and bind `html<ParentMessage>()` inside. The view stays decoupled from any particular parent and composes through the `toParentMessage` callback the parent supplies.
+
 Use `empty` (not `null`) for conditional rendering. Use `M.value().pipe(M.tagsExhaustive({...}))` for rendering discriminated unions and `Array.match` for rendering lists that may be empty.
 
 Use `keyed` wrappers whenever the view branches into structurally different layouts based on route or model state. Without keying, the virtual DOM will try to diff one layout into another (e.g. a full-width landing page into a sidebar docs layout), which causes stale DOM, mismatched event handlers, and subtle rendering bugs. Key the outermost container of each layout branch with a stable string (e.g. `keyed('div')('landing', ...)` vs `keyed('div')('docs', ...)`). Within a single layout, key the content area on the route tag (e.g. `keyed('div')(model.route._tag, ...)`) so page transitions replace rather than patch.
@@ -89,31 +99,38 @@ Command definitions live where they're produced — colocated with the update fu
 
 ### Mount
 
-For per-element DOM work — focusing an input, handing the live `Element` to a third-party library — define a Mount with `Mount.define` and attach it to a view element with `OnMount`. The runtime runs the Effect when the element mounts, dispatches its result Message back through `update`, and runs the paired cleanup on unmount.
+For per-element DOM work that needs the live `Element` handle (anchor positioning, portaling an overlay, attaching observers, handing the element to a third-party library), define a Mount with `Mount.define` and attach it to a view element with `OnMount`. The runtime runs the Effect when the element mounts, dispatches its result Message back through `update`, and runs the paired cleanup on unmount.
 
 ```ts
-const CompletedFocusInput = m('CompletedFocusInput')
+const CompletedPortalToBody = m('CompletedPortalToBody')
 
-const FocusInput = Mount.define('FocusInput', CompletedFocusInput)
+const PortalToBody = Mount.define('PortalToBody', CompletedPortalToBody)
 
-const focusInput = FocusInput(element =>
+const portalToBody = PortalToBody(element =>
   Effect.sync(() => {
-    if (element instanceof HTMLInputElement) {
-      element.focus()
-    }
+    document.body.appendChild(element)
     return {
-      message: CompletedFocusInput(),
-      cleanup: Function.constVoid,
+      message: CompletedPortalToBody(),
+      cleanup: () => element.remove(),
     }
   }),
 )
 
 // In view:
-input([Type('search'), OnMount(focusInput)])
+div([Class('fixed inset-0 bg-black/50'), OnMount(portalToBody)])
 ```
 
 Cleanup is data, paired with setup as a single value. For setup with no cleanup, pass `Function.constVoid`. The `Completed*` Message marks the lifecycle without forcing a meaningful response in update.
 
+Two rules for Mount, both must hold:
+
+1. **The Effect uses the element parameter.** Mount provides the live element handle, and that handle is what makes Mount distinct from Command. If your Effect doesn't read or write the element, pick a different primitive.
+2. **The work is DOM measurement or DOM manipulation on that element.** Read its geometry, mutate its CSS, attach an observer to it, portal it, hand it to a third-party library. Anything else (network, storage, focus-on-transition, scroll lock for the page) belongs in a Command returned from `update`.
+
+Mount Effects re-run during DevTools time-travel renders. The two rules above keep Mount work inherently replay-safe (read-only measurement, idempotent DOM mutation, paired observer attach + cleanup).
+
+Don't reach for Mount just because the work happens to coincide with an element appearing. Check what causes the work. If a Message just dispatched (like `Opened`), the cause is the Message, not the element. Use a Command returned from `update`'s handler instead. Example: focusing a search input when its dialog opens. The cause is `Opened`, not the input's existence; return a `FocusInput` Command from the `Opened` handler.
+
 ### File Organization
 
 Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) to make files easier to skim. These are for wayfinding — they make it clear where things live and where new code should go. Use domain-specific headers too when it helps (e.g. `// PHYSICS`, `// ROUTING`).
@@ -187,7 +204,7 @@ Use `typeof ClickedSubmit` in type positions to reference a schema value's type.
 - Avoid `let`. Use `const` and prefer immutable patterns.
 - Always use braces for control flow. `if (foo) { return true }` not `if (foo) return true`.
 - Use `is*` for boolean naming e.g. `isPlaying`, `isValid`.
-- Don't add inline or block comments to explain code — if code needs explanation, refactor for clarity or use better names. Exceptions: section headers (see File Organization above) and TSDoc (`/** ... */`) on public exports.
+- Don't add inline or block comments to explain code. If code needs explanation, refactor for clarity or use better names. Exceptions: section headers (see File Organization above), TSDoc (`/** ... */`) on public exports, and `// NOTE:` comments. Reserve `// NOTE:` for behavior that would mislead a careful reader into breaking things: a timing dependency that's silent if violated, a workaround for an upstream bug, a browser quirk that costs real debugging time to rediscover. The bar is high. When in doubt, delete it.
 - Use capitalized string literals for Schema literal types: `S.Literals(['Horizontal', 'Vertical'])` not `S.Literals(['horizontal', 'vertical'])`.
 - Capitalize namespace imports: `import * as Command from './command'` not `import * as command from './command'`.
 - Extract magic numbers to named constants. No raw numeric literals in logic.