create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/websocket-chat/src/scene.test.ts

@@ -0,0 +1,166 @@
+import { DateTime } from 'effect'
+import {
+  Command,
+  ManagedResource,
+  Subscription,
+  click,
+  expect,
+  given,
+  placeholder,
+  role,
+  scene,
+  text,
+  type,
+} from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import {
+  ConnectionConnected,
+  ConnectionConnecting,
+  ConnectionDisconnected,
+  ConnectionError,
+  Message,
+  Model,
+  SendMessage,
+  TimestampReceivedMessage,
+  TimestampSentMessage,
+  managedResources,
+  update,
+  view,
+} from './main'
+
+const idleModel = Model.make({
+  connection: ConnectionDisconnected(),
+  messages: [],
+  messageInput: '',
+})
+
+const zonedAt = (timestamp: number) =>
+  DateTime.makeZonedUnsafe(timestamp, { timeZone: 'UTC' })
+
+describe('view', () => {
+  test('initial view shows the heading, status, and a Connect button', () => {
+    scene(
+      { update, view },
+      given(idleModel),
+      expect(text('WebSocket Chat')).toExist(),
+      expect(text('Disconnected')).toExist(),
+      expect(role('button', { name: 'Connect to Chat' })).toExist(),
+      expect(text('No messages yet')).toExist(),
+    )
+  })
+
+  test('connecting state renders the Connecting message', () => {
+    scene(
+      { update, view },
+      given({ ...idleModel, connection: ConnectionConnecting() }),
+      expect(text('Connecting...')).toExist(),
+    )
+  })
+
+  test('connected state shows the message input and Send button', () => {
+    scene(
+      { update, view },
+      given({ ...idleModel, connection: ConnectionConnected() }),
+      expect(placeholder('Type a message...')).toExist(),
+      expect(role('button', { name: 'Send' })).toBeDisabled(),
+      type(placeholder('Type a message...'), 'hi'),
+      expect(role('button', { name: 'Send' })).toBeEnabled(),
+    )
+  })
+
+  test('error state renders the error and a Try Again button', () => {
+    scene(
+      { update, view },
+      given({
+        ...idleModel,
+        connection: ConnectionError({ error: 'Connection refused' }),
+      }),
+      expect(text('Connection Error')).toExist(),
+      expect(text('Connection refused')).toExist(),
+      expect(role('button', { name: 'Try Again' })).toExist(),
+    )
+  })
+
+  test('messages render in the conversation list', () => {
+    scene(
+      { update, view },
+      given({
+        ...idleModel,
+        connection: ConnectionConnected(),
+        messages: [
+          { text: 'Hello there', zoned: zonedAt(0), isSent: true },
+          { text: 'General Kenobi', zoned: zonedAt(0), isSent: false },
+        ],
+      }),
+      expect(text('Hello there')).toExist(),
+      expect(text('General Kenobi')).toExist(),
+      expect(text('No messages yet')).toBeAbsent(),
+    )
+  })
+
+  test('a successful acquisition connects the chat and the user can send a message', () => {
+    scene(
+      { update, view },
+      given(idleModel),
+      click(role('button', { name: 'Connect to Chat' })),
+      expect(text('Connecting...')).toExist(),
+      ManagedResource.acquire(managedResources.chatSocket),
+      expect(placeholder('Type a message...')).toExist(),
+      type(placeholder('Type a message...'), 'hi there'),
+      click(role('button', { name: 'Send' })),
+      Command.expectExact(SendMessage({ text: 'hi there' })),
+      Command.resolve(
+        SendMessage,
+        Message.SucceededSendMessage({ text: 'hi there' }),
+      ),
+      Command.resolve(
+        TimestampSentMessage,
+        Message.TimestampedMessage({
+          text: 'hi there',
+          zoned: zonedAt(0),
+          isSent: true,
+        }),
+      ),
+      expect(text('hi there')).toExist(),
+      expect(text('No messages yet')).toBeAbsent(),
+    )
+  })
+
+  test('a failed socket acquisition shows the connection error', () => {
+    scene(
+      { update, view },
+      given(idleModel),
+      click(role('button', { name: 'Connect to Chat' })),
+      expect(text('Connecting...')).toExist(),
+      ManagedResource.failAcquire(
+        managedResources.chatSocket,
+        new Error('Connection timeout'),
+      ),
+      expect(text('Connection Error')).toExist(),
+      expect(text('Connection timeout')).toExist(),
+      expect(role('button', { name: 'Try Again' })).toExist(),
+    )
+  })
+
+  test('a message arriving on the socket Subscription lands in the conversation', () => {
+    scene(
+      { update, view },
+      given({ ...idleModel, connection: ConnectionConnected() }),
+      Subscription.emit(Message.ReceivedMessage({ text: 'hello from echo' })),
+      Command.expectExact(
+        TimestampReceivedMessage({ text: 'hello from echo' }),
+      ),
+      Command.resolve(
+        TimestampReceivedMessage,
+        Message.TimestampedMessage({
+          text: 'hello from echo',
+          zoned: zonedAt(0),
+          isSent: false,
+        }),
+      ),
+      expect(text('hello from echo')).toExist(),
+      expect(text('No messages yet')).toBeAbsent(),
+    )
+  })
+})

package/dist/templates/examples/websocket-chat/src/story.test.ts

@@ -0,0 +1,183 @@
+import { DateTime } from 'effect'
+import { Command, given, message, model, story } from 'foldkit/story'
+import { describe, expect, test } from 'vitest'
+
+import {
+  ConnectionConnected,
+  ConnectionConnecting,
+  ConnectionDisconnected,
+  Message,
+  type Model,
+  SendMessage,
+  TimestampReceivedMessage,
+  TimestampSentMessage,
+  update,
+} from './main'
+
+const idleModel: Model = {
+  connection: ConnectionDisconnected(),
+  messages: [],
+  messageInput: '',
+}
+
+const connectedModel: Model = {
+  ...idleModel,
+  connection: ConnectionConnected(),
+}
+
+const zonedNow = DateTime.makeZonedUnsafe(0, { timeZone: 'UTC' })
+
+describe('update', () => {
+  describe('connection state', () => {
+    test('ClickedConnect moves into ConnectionConnecting', () => {
+      story(
+        update,
+        given(idleModel),
+        message(Message.ClickedConnect()),
+        model(model => {
+          expect(model.connection._tag).toBe('ConnectionConnecting')
+        }),
+      )
+    })
+
+    test('Connected moves into ConnectionConnected', () => {
+      story(
+        update,
+        given({ ...idleModel, connection: ConnectionConnecting() }),
+        message(Message.Connected()),
+        model(model => {
+          expect(model.connection._tag).toBe('ConnectionConnected')
+        }),
+      )
+    })
+
+    test('Disconnected returns to ConnectionDisconnected and clears messages', () => {
+      story(
+        update,
+        given({
+          ...connectedModel,
+          messages: [{ text: 'old', zoned: zonedNow, isSent: true }],
+        }),
+        message(Message.Disconnected()),
+        model(model => {
+          expect(model.connection._tag).toBe('ConnectionDisconnected')
+          expect(model.messages).toHaveLength(0)
+        }),
+      )
+    })
+
+    test('FailedConnect captures the error message', () => {
+      story(
+        update,
+        given({ ...idleModel, connection: ConnectionConnecting() }),
+        message(Message.FailedConnect({ error: 'Timeout' })),
+        model(model => {
+          if (model.connection._tag === 'ConnectionError') {
+            expect(model.connection.error).toBe('Timeout')
+          } else {
+            throw new Error('Expected ConnectionError')
+          }
+        }),
+      )
+    })
+  })
+
+  describe('message input', () => {
+    test('UpdatedMessageInput stores the new input value', () => {
+      story(
+        update,
+        given(connectedModel),
+        message(Message.UpdatedMessageInput({ value: 'Hello' })),
+        model(model => {
+          expect(model.messageInput).toBe('Hello')
+        }),
+      )
+    })
+  })
+
+  describe('SubmittedMessage', () => {
+    test('an empty input is ignored', () => {
+      story(
+        update,
+        given({ ...connectedModel, messageInput: '' }),
+        message(Message.SubmittedMessage()),
+        Command.expectNone(),
+      )
+    })
+
+    test('whitespace-only input is ignored', () => {
+      story(
+        update,
+        given({ ...connectedModel, messageInput: '   ' }),
+        message(Message.SubmittedMessage()),
+        Command.expectNone(),
+      )
+    })
+
+    test('connected client fires SendMessage and clears the input', () => {
+      story(
+        update,
+        given({ ...connectedModel, messageInput: 'Hello there' }),
+        message(Message.SubmittedMessage()),
+        model(model => {
+          expect(model.messageInput).toBe('')
+        }),
+        Command.expectHas(SendMessage),
+        Command.resolve(
+          SendMessage,
+          Message.SucceededSendMessage({ text: 'Hello there' }),
+        ),
+        Command.expectHas(TimestampSentMessage),
+        Command.resolve(
+          TimestampSentMessage,
+          Message.TimestampedMessage({
+            text: 'Hello there',
+            zoned: zonedNow,
+            isSent: true,
+          }),
+        ),
+        model(model => {
+          expect(model.messages).toHaveLength(1)
+          expect(model.messages[0]?.text).toBe('Hello there')
+          expect(model.messages[0]?.isSent).toBe(true)
+        }),
+      )
+    })
+
+    test('disconnected client ignores SubmittedMessage', () => {
+      story(
+        update,
+        given({ ...idleModel, messageInput: 'Hello' }),
+        message(Message.SubmittedMessage()),
+        Command.expectNone(),
+        model(model => {
+          expect(model.messageInput).toBe('Hello')
+        }),
+      )
+    })
+  })
+
+  describe('inbound messages', () => {
+    test('ReceivedMessage queues TimestampReceivedMessage that appends to the list', () => {
+      story(
+        update,
+        given(connectedModel),
+        message(Message.ReceivedMessage({ text: 'echo' })),
+        Command.expectHas(TimestampReceivedMessage),
+        Command.resolve(
+          TimestampReceivedMessage,
+          Message.TimestampedMessage({
+            text: 'echo',
+            zoned: zonedNow,
+            isSent: false,
+          }),
+        ),
+        model(model => {
+          expect(model.messages).toHaveLength(1)
+          expect(model.messages[0]?.isSent).toBe(false)
+          expect(model.messages[0]?.text).toBe('echo')
+        }),
+      )
+    })
+  })
+})

package/dist/templates/examples/websocket-chat/src/styles.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/dist/templates/examples/websocket-chat/src/vitest-setup.ts

@@ -0,0 +1,3 @@
+import { setup } from 'foldkit/test/vitest'
+
+setup()

package/dist/templates/release.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "channel": "stable",
+  "sourceCommit": "0ad2f3984e366dc3fd31727a28ed1c48926c4a5b",
+  "packages": {
+    "create-foldkit-app": "0.28.0",
+    "@foldkit/devtools": "0.149.0",
+    "@foldkit/devtools-mcp": "0.16.1",
+    "foldkit": "0.149.0",
+    "@foldkit/markdown": "0.5.0",
+    "@foldkit/oxlint-plugin": "0.7.0",
+    "@foldkit/ui": "0.149.0",
+    "@foldkit/vite-plugin": "0.16.2"
+  },
+  "dependencies": {
+    "@foldkit/devtools": "0.149.0",
+    "@foldkit/vite-plugin": "0.16.2",
+    "@foldkit/devtools-mcp": "0.16.1",
+    "@foldkit/oxlint-plugin": "0.7.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^25.9.3",
+    "happy-dom": "^20.10.4",
+    "oxlint": "^1.70.0",
+    "prettier": "^3.8.4",
+    "vitest": "^4.1.9"
+  }
+}

package/dist/templates/rendering/ssg/src/entry.ts

@@ -0,0 +1,20 @@
+import { Runtime } from 'foldkit'
+
+import { Message, Model, init, update, view } from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  init,
+  update,
+  view,
+  container: document.getElementById('root'),
+  routing: {
+    onUrlRequest: request => Message.ClickedLink({ request }),
+    onUrlChange: url => Message.ChangedUrl({ url }),
+  },
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID })

package/{templates → dist/templates}/rendering/ssg/src/main.ts

@@ -1,7 +1,7 @@
 import { Effect, Match as M, Schema as S, pipe } from 'effect'
 import { Command, Runtime } from 'foldkit'
 import { type Document, type Html, type HtmlBuilder } from 'foldkit/html'
-import { m } from 'foldkit/message'
+import { defineMessageUnion } from 'foldkit/message'
 import { UrlRequest, load, pushUrl } from 'foldkit/navigation'
 import { evo } from 'foldkit/struct'
 import { Url, toString as urlToString } from 'foldkit/url'
@@ -18,19 +18,14 @@ export type Model = typeof Model.Type
 
 // MESSAGE
 
-export const ClickedIncrement = m('ClickedIncrement')
-export const ClickedLink = m('ClickedLink', { request: UrlRequest })
-export const ChangedUrl = m('ChangedUrl', { url: Url })
-export const CompletedNavigateInternal = m('CompletedNavigateInternal')
-export const CompletedLoadExternal = m('CompletedLoadExternal')
-
-export const Message = S.Union([
-  ClickedIncrement,
-  ClickedLink,
-  ChangedUrl,
-  CompletedNavigateInternal,
-  CompletedLoadExternal,
-])
+export const Message = defineMessageUnion({
+  ClickedIncrement: {},
+  ClickedLink: { request: UrlRequest },
+  ChangedUrl: { url: Url },
+  CompletedNavigateInternal: {},
+  CompletedLoadExternal: {},
+})
+
 export type Message = typeof Message.Type
 
 // INIT
@@ -44,15 +39,16 @@ export const init: Runtime.RoutingApplicationInit<Model, Message> = url => [
 
 const NavigateInternal = Command.define('NavigateInternal', {
   args: { url: S.String },
-  messages: [CompletedNavigateInternal],
+  messages: [Message.CompletedNavigateInternal],
   execute: ({ url }) =>
-    pushUrl(url).pipe(Effect.as(CompletedNavigateInternal())),
+    pushUrl(url).pipe(Effect.as(Message.CompletedNavigateInternal())),
 })
 
 const LoadExternal = Command.define('LoadExternal', {
   args: { href: S.String },
-  messages: [CompletedLoadExternal],
-  execute: ({ href }) => load(href).pipe(Effect.as(CompletedLoadExternal())),
+  messages: [Message.CompletedLoadExternal],
+  execute: ({ href }) =>
+    load(href).pipe(Effect.as(Message.CompletedLoadExternal())),
 })
 
 // UPDATE
@@ -60,30 +56,27 @@ const LoadExternal = Command.define('LoadExternal', {
 type UpdateReturn = readonly [Model, ReadonlyArray<Command.Command<Message>>]
 const withUpdateReturn = M.withReturnType<UpdateReturn>()
 
-export const update = (model: Model, message: Message): UpdateReturn =>
-  M.value(message).pipe(
-    withUpdateReturn,
-    M.tagsExhaustive({
-      ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
-      ClickedLink: ({ request }) =>
-        M.value(request).pipe(
-          withUpdateReturn,
-          M.tagsExhaustive({
-            Internal: ({ url }) => [
-              model,
-              [NavigateInternal({ url: urlToString(url) })],
-            ],
-            External: ({ href }) => [model, [LoadExternal({ href })]],
-          }),
-        ),
-      ChangedUrl: ({ url }) => [
-        evo(model, { route: () => urlToAppRoute(url) }),
-        [],
-      ],
-      CompletedNavigateInternal: () => [model, []],
-      CompletedLoadExternal: () => [model, []],
-    }),
-  )
+export const update = (model: Model, message: Message) =>
+  Message.match<UpdateReturn>(message, {
+    ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
+    ClickedLink: ({ request }) =>
+      M.value(request).pipe(
+        withUpdateReturn,
+        M.tagsExhaustive({
+          Internal: ({ url }) => [
+            model,
+            [NavigateInternal({ url: urlToString(url) })],
+          ],
+          External: ({ href }) => [model, [LoadExternal({ href })]],
+        }),
+      ),
+    ChangedUrl: ({ url }) => [
+      evo(model, { route: () => urlToAppRoute(url) }),
+      [],
+    ],
+    CompletedNavigateInternal: () => [model, []],
+    CompletedLoadExternal: () => [model, []],
+  })
 
 // VIEW
 
@@ -130,7 +123,7 @@ const pageView = (model: Model, h: HtmlBuilder<Message>): Html =>
             ),
             h.button(
               [
-                h.OnClick(ClickedIncrement()),
+                h.OnClick(Message.ClickedIncrement()),
                 h.Class('w-fit bg-black px-4 py-2 text-white'),
               ],
               [`Count: ${model.count}`],

package/dist/templates/rendering/ssg/src/route.ts

@@ -0,0 +1,20 @@
+import { Schema as S, pipe } from 'effect'
+import { Route } from 'foldkit'
+import { literal, r } from 'foldkit/route'
+
+export const HomeRoute = r('Home')
+export const AboutRoute = r('About')
+export const NotFoundRoute = r('NotFound', { path: S.String })
+
+export const AppRoute = S.Union([HomeRoute, AboutRoute, NotFoundRoute])
+export type AppRoute = typeof AppRoute.Type
+
+export const homeRouter = pipe(Route.root, Route.mapTo(HomeRoute))
+export const aboutRouter = pipe(literal('about'), Route.mapTo(AboutRoute))
+
+const routeParser = Route.oneOf(aboutRouter, homeRouter)
+
+export const urlToAppRoute = Route.parseUrlWithFallback(
+  routeParser,
+  NotFoundRoute,
+)

package/dist/templates/rendering/ssg/src/vite-env.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="vite/client" />
+
+// `@foldkit/vite-plugin` compiles the deployment's build id in here, from its
+// `buildId` option or the `FOLDKIT_BUILD_ID` environment variable. The server
+// entry hands it to `renderToString` and the client entry to `Runtime.hydrate`,
+// which is how hydration tells a page from this deployment apart from one served
+// by another.
+//
+// Declared as required rather than optional because this project's build always
+// supplies one. A build that did not would produce `undefined` here, and both
+// entries refuse it at runtime; typing it as optional would only push that
+// failure past the compiler and into the served page.
+interface ImportMetaEnv {
+  readonly FOLDKIT_BUILD_ID: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/dist/templates/rendering/ssr/src/entry.ts

@@ -0,0 +1,17 @@
+import { Runtime } from 'foldkit'
+
+import { Flags, Message, Model, init, update, view } from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  Flags,
+  init,
+  update,
+  view,
+  container: document.getElementById('root'),
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID })

package/{templates → dist/templates}/rendering/ssr/src/main.ts

@@ -1,7 +1,7 @@
-import { Effect, Match as M, Schema as S } from 'effect'
+import { Effect, Schema as S } from 'effect'
 import { Command, Runtime } from 'foldkit'
 import { type Document, type HtmlBuilder } from 'foldkit/html'
-import { m } from 'foldkit/message'
+import { defineMessageUnion } from 'foldkit/message'
 import { evo } from 'foldkit/struct'
 
 import { Button } from '@foldkit/ui'
@@ -28,28 +28,20 @@ export type Flags = typeof Flags.Type
 
 // MESSAGE
 
-export const ClickedDecrement = m('ClickedDecrement')
-export const ClickedIncrement = m('ClickedIncrement')
-export const CompletedPersistCount = m('CompletedPersistCount')
+export const Message = defineMessageUnion({
+  ClickedDecrement: {},
+  ClickedIncrement: {},
+  CompletedPersistCount: {},
+})
 
-export const Message = S.Union([
-  ClickedDecrement,
-  ClickedIncrement,
-  CompletedPersistCount,
-])
 export type Message = typeof Message.Type
 
 // UPDATE
 
-export const update = (
-  model: Model,
-  message: Message,
-): readonly [Model, ReadonlyArray<Command.Command<Message>>] =>
-  M.value(message).pipe(
-    M.withReturnType<
-      readonly [Model, ReadonlyArray<Command.Command<Message>>]
-    >(),
-    M.tagsExhaustive({
+export const update = (model: Model, message: Message) =>
+  Message.match<readonly [Model, ReadonlyArray<Command.Command<Message>>]>(
+    message,
+    {
       ClickedDecrement: () => {
         const nextCount = model.count - 1
         return [
@@ -65,7 +57,7 @@ export const update = (
         ]
       },
       CompletedPersistCount: () => [model, []],
-    }),
+    },
   )
 
 // COMMAND
@@ -74,13 +66,13 @@ const COUNT_COOKIE_MAX_AGE_SECONDS = 31536000
 
 export const PersistCount = Command.define('PersistCount', {
   args: { count: S.Number },
-  messages: [CompletedPersistCount],
+  messages: [Message.CompletedPersistCount],
   execute: ({ count }) =>
     Effect.try(() => {
       document.cookie = `${COUNT_COOKIE}=${count}; path=/; max-age=${COUNT_COOKIE_MAX_AGE_SECONDS}`
     }).pipe(
-      Effect.map(() => CompletedPersistCount()),
-      Effect.catch(() => Effect.succeed(CompletedPersistCount())),
+      Effect.map(() => Message.CompletedPersistCount()),
+      Effect.catch(() => Effect.succeed(Message.CompletedPersistCount())),
     ),
 })
 
@@ -119,7 +111,7 @@ export const view = (model: Model, h: HtmlBuilder<Message>): Document => ({
         [
           Button.view(
             {
-              onClick: ClickedDecrement(),
+              onClick: Message.ClickedDecrement(),
               toView: attributes =>
                 h.button([...attributes.button, h.Class(buttonStyle)], ['-']),
             },
@@ -127,7 +119,7 @@ export const view = (model: Model, h: HtmlBuilder<Message>): Document => ({
           ),
           Button.view(
             {
-              onClick: ClickedIncrement(),
+              onClick: Message.ClickedIncrement(),
               toView: attributes =>
                 h.button([...attributes.button, h.Class(buttonStyle)], ['+']),
             },