create-foldkit-app 0.20.1 → 0.21.1

package/README.md

@@ -38,6 +38,7 @@ The CLI prompts you for a project name, starter example, and package manager. Pa
 | `generative-art`         | Perlin-noise flow field with evolving particle trails, mouse vortex, and high-frequency Messages       |
 | `auth`                   | Authentication with Submodels, OutMessage, and protected routes                                        |
 | `shopping-cart`          | Complex state management with nested Models and routing                                                |
+| `checkout-machine`       | Experimental state machine checkout with guarded branches and edge Commands                            |
 | `pixel-art`              | Pixel editor with undo/redo, UI components, and localStorage persistence                               |
 | `websocket-chat`         | Managed resources with WebSocket integration                                                           |
 | `managed-resource-layer` | Layer-backed ManagedResource lifecycle with an Effect service                                          |

package/dist/examples.js

@@ -11,12 +11,14 @@ export const EXAMPLE_VALUES = [
     'api-cache',
     'charting',
     'routing',
+    'route-transitions',
     'query-sync',
     'snake',
     'canvas-art',
     'generative-art',
     'auth',
     'shopping-cart',
+    'checkout-machine',
     'pixel-art',
     'websocket-chat',
     'managed-resource-layer',
@@ -87,6 +89,11 @@ export const examples = [
         title: 'routing',
         description: 'URL routing with parser combinators and route parameters',
     },
+    {
+        value: 'route-transitions',
+        title: 'route-transitions',
+        description: 'Live transition log with entry, exit, and stayed navigation policies',
+    },
     {
         value: 'query-sync',
         title: 'query-sync',
@@ -117,6 +124,11 @@ export const examples = [
         title: 'shopping-cart',
         description: 'Complex state management with nested models and routing',
     },
+    {
+        value: 'checkout-machine',
+        title: 'checkout-machine',
+        description: 'Checkout workflow powered by the experimental state machine module with guarded branches and edge Commands',
+    },
     {
         value: 'pixel-art',
         title: 'pixel-art',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.20.1",
+  "version": "0.21.1",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,15 +12,15 @@
     "templates"
   ],
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.88",
-    "@effect/platform-node-shared": "4.0.0-beta.88",
+    "@effect/platform-node": "4.0.0-beta.97",
+    "@effect/platform-node-shared": "4.0.0-beta.97",
     "chalk": "^5.6.2",
-    "effect": "4.0.0-beta.88",
+    "effect": "4.0.0-beta.97",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-beta.88",
+    "@effect/vitest": "4.0.0-beta.97",
     "@types/node": "^25.9.3",
     "vitest": "^4.1.9"
   },

package/templates/base/.oxlintrc.json

@@ -1,12 +1,7 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "extends": ["./node_modules/@foldkit/oxlint-plugin/recommended.json"],
   "plugins": ["typescript"],
-  "jsPlugins": [
-    {
-      "name": "foldkit",
-      "specifier": "@foldkit/oxlint-plugin"
-    }
-  ],
   "categories": {
     "correctness": "off"
   },
@@ -24,15 +19,7 @@
     "typescript/consistent-type-assertions": [
       "error",
       { "assertionStyle": "never" }
-    ],
-    "foldkit/no-noop-message": "error",
-    "foldkit/got-submodel-message-name": "error",
-    "foldkit/message-binding-matches-tag": "error",
-    "foldkit/got-prefix-requires-submodel-payload": "error",
-    "foldkit/no-empty-object-tagged-call": "error",
-    "foldkit/prefer-callable-message-constructor": "error",
-    "foldkit/command-binding-matches-name": "error",
-    "foldkit/no-module-level-mutable-state": "error"
+    ]
   },
   "ignorePatterns": [
     "dist/",

package/templates/base/AGENTS.md

@@ -54,7 +54,7 @@ Use `evo()` from `foldkit/struct` for immutable model updates. Never spread or `
 
 Bind the `html` factory inside each view function with `const h = html<Message>()` (never at module level), then reach for `h.div`, `h.OnClick`, etc. off the returned record. Use `empty` (not `null`) for conditional rendering, `M.value().pipe(M.tagsExhaustive({...}))` for discriminated unions, and `Array.match` for 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 tries to diff one layout into another, causing stale DOM and event handler mismatches.
+Key every view branch based on route or model state, even when the branch root tags differ. Key inline branch roots directly (never a wrapper introduced only to carry a key); when the branches delegate to other view functions, key a single wrapper at the branch site with the discriminating key, for example `h.keyed('div')(model.route._tag, [], [routeContent])`. Without keying, the virtual DOM tries to diff one layout into another, causing stale DOM and event handler mismatches.
 
 ### Commands
 
@@ -66,7 +66,9 @@ For DOM operations (focus, scroll, modals, scroll lock), Foldkit ships a `Dom` m
 
 ### File Organization
 
-A Foldkit app lives in two files. `src/main.ts` holds the pure definitions (Model, Messages, init, update, view). `src/entry.ts` imports them and boots the runtime with `Runtime.makeApplication` and `Runtime.run`. `index.html` references `entry.ts`. The split keeps `main.ts` importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+The invariant: keep the runtime boot separate from the pure definitions. `src/entry.ts` calls `Runtime.makeApplication` and `Runtime.run`, and `index.html` references it. The definitions (Model, Messages, init, update, view, Commands) never call `Runtime.run`, so they stay importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+
+For a small app the definitions all fit in one `src/main.ts`. Split a unit into its own file when it has _both_ a distinct reason to change _and_ a name you'd give it unprompted: the pure domain core into `timer.ts` or `domain.ts`, the view into `view.ts` (or a `components/` directory), a Command's owned resource into its own module. Split on that revealed seam, not on line count alone. A file that has grown large is _evidence_ a seam has formed, so treat its size as a prompt to re-check for one. Two splits are forced: extract Messages to `message.ts` when Commands need the constructors (this breaks the cycle between `command.ts` and `main.ts`), and colocate Commands with the update that returns them. Exemplars: counter and stopwatch are a single `main.ts`; kanban splits `domain` / `command` / `message` / `model`; typing-game splits views by page.
 
 Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) for wayfinding.