create-hyper-effect 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Potti1234
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# create-hyper-effect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Creates a hyper-effect app from `template/`: one page with sign-in, live shared state, a validated form, regions, crease/ui components, Story and HTTP tests, and a Playwright browser check.
+
+```sh
+npm create hyper-effect my-app             # anywhere → ./my-app, then npm install
+npm run create -- my-app --title "My App"   # at the monorepo root → apps/my-app
+npm install                                # links the new workspace
+cd apps/my-app && npm start                # http://localhost:4000
+```
+
+Outside the monorepo, `npm create hyper-effect my-app` creates `./my-app`, depending on the `@hyper-effect/core` version published with it, with the hyper-effect agent skill in `.claude/skills`. Inside the monorepo the app goes to `apps/<name>` (a workspace on the local packages). `--core <version>` overrides the dependency (`file:<tarball>` for a packed build) and `--dir` the target.
+
+The template is a working app, not a stub: `apps/starter` is generated from it, and its tests and browser check run with the rest. Change the template, regenerate `starter` (or apply the change to it), and run `npm run check` there.
+
+Agents building on a generated app use the `hyper-effect` skill in `.claude/skills/hyper-effect`.

package/bin.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/* create-hyper-effect: a new hyper-effect app from the template.
+
+   usage: create-hyper-effect <name> [--title "My App"] [--dir <path>] [--core <version>]
+
+   Run with `npm create hyper-effect@latest <name>`: the app depends on the
+   @hyper-effect/core version this package was published with, and gets the
+   hyper-effect agent skill in .claude/skills. Run from inside the
+   hyper-effect monorepo, the app goes to apps/<name>, a workspace that uses
+   the monorepo's packages. --core overrides the dependency (a version, or
+   file:<tarball> for a packed build). */
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE = join(HERE, 'template')
+/** The agent skill, staged into the published package by tools/build/pack.mjs. */
+const SKILL = join(HERE, 'skill')
+const { version } = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8'))
+/** Files renamed on the way: npm would treat them specially in the package. */
+const RENAMES = { '_package.json': 'package.json', _gitignore: '.gitignore' }
+const TEXT = /\.(ts|mjs|js|json|md|css|html|txt)$|^_?gitignore$/
+
+const fail = message => {
+  console.error(`create-hyper-effect: ${message}`)
+  process.exit(1)
+}
+
+const args = process.argv.slice(2)
+const option = name => {
+  const index = args.indexOf(`--${name}`)
+  if (index === -1) return undefined
+  const value = args[index + 1]
+  if (value === undefined || value.startsWith('--')) fail(`--${name} needs a value`)
+  args.splice(index, 2)
+  return value
+}
+const title = option('title')
+const dir = option('dir')
+const core = option('core')
+const [name] = args
+if (name === undefined || !/^[a-z][a-z0-9-]{0,50}$/.test(name)) {
+  fail('usage: create-hyper-effect <name> [--title "My App"] [--dir <path>] [--core <version>]\n  <name>: lowercase letters, digits and dashes, starting with a letter')
+}
+
+/** The hyper-effect monorepo containing `from`, if any. */
+const findMonorepo = from => {
+  for (let current = resolve(from); ; current = dirname(current)) {
+    const manifest = join(current, 'package.json')
+    if (existsSync(manifest) && JSON.parse(readFileSync(manifest, 'utf8')).name === 'hyper-effect-monorepo') return current
+    if (dirname(current) === current) return undefined
+  }
+}
+
+const monorepo = findMonorepo(process.cwd())
+if (monorepo === undefined && core === undefined && version === '0.0.0') {
+  fail('this is an unpublished build: run it inside the hyper-effect monorepo (the app goes to apps/<name>), or pass --core <version>.')
+}
+const target = resolve(dir ?? (monorepo === undefined ? name : join(monorepo, 'apps', name)))
+if (existsSync(target) && readdirSync(target).length > 0) fail(`${target} exists and is not empty`)
+
+const values = {
+  name,
+  title: title ?? name.split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' '),
+  // Inside the monorepo, npm workspaces link the local package.
+  coreVersion: core ?? (monorepo === undefined ? version : '*'),
+}
+const fill = text => text.replace(/\{\{(name|title|coreVersion)\}\}/g, (_, key) => values[key])
+
+const copy = (from, to) => {
+  mkdirSync(to, { recursive: true })
+  for (const entry of readdirSync(from)) {
+    const source = join(from, entry)
+    const destination = join(to, RENAMES[entry] ?? entry)
+    if (statSync(source).isDirectory()) copy(source, destination)
+    else if (TEXT.test(entry)) writeFileSync(destination, fill(readFileSync(source, 'utf8')))
+    else writeFileSync(destination, readFileSync(source))
+  }
+}
+copy(TEMPLATE, target)
+if (monorepo === undefined && existsSync(SKILL)) {
+  cpSync(SKILL, join(target, '.claude', 'skills', 'hyper-effect'), { recursive: true })
+}
+
+const shown = relative(process.cwd(), target) || '.'
+console.log(`Created ${values.title} in ${shown}.
+
+Next:
+${monorepo === undefined ? `  cd ${shown}\n  npm install` : '  npm install            # at the monorepo root: links the new workspace'}
+  cd ${shown}
+  npm start              # http://localhost:4000, sign in with any name
+  npm test
+  npm run check          # the browser check, against the running server
+
+Agents: the hyper-effect skill (.claude/skills/hyper-effect) explains how to build on it.`)

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "create-hyper-effect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Creates a hyper-effect app: one page with sign-in, live shared state, a form, regions, tests and a browser check.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Potti1234/hyper-effect.git",
+    "directory": "packages/create-hyper-effect"
+  },
+  "homepage": "https://github.com/Potti1234/hyper-effect/tree/main/packages/create-hyper-effect#readme",
+  "bugs": "https://github.com/Potti1234/hyper-effect/issues",
+  "keywords": [
+    "foldkit",
+    "effect",
+    "datastar",
+    "create",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "type": "module",
+  "bin": {
+    "create-hyper-effect": "bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "template",
+    "skill"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: hyper-effect
+description: Use whenever building or changing a hyper-effect app or page — server-side Foldkit programs on Effect, driven by Datastar. Triggers on imports from `@hyper-effect/core` or `@hyper-effect/island`, on files under apps/, examples/ or packages/ of the hyper-effect repository, on `npm run create`, and on requests like "add a page", "build an app with hyper-effect", "make this live/real-time", "add a form/list/upload to the app". Explains the architecture, the rules that keep pages correct and secure, the workflow, and where working references live.
+---
+
+# hyper-effect
+
+hyper-effect runs Foldkit programs on the server. Model, Message, `update`, `view`, Commands and Subscriptions are plain Foldkit; the update loop runs in a server session per open page, the view is rendered on the server, and Datastar in the browser applies the morphs and posts events. There is no client-side state to manage, no API layer, and no JSON contract between front and back: a page is one Foldkit program.
+
+Load the **foldkit** skill as well: everything about Model, Message, update, view, Commands, Subscriptions, Foldkit UI and Story/Scene tests is Foldkit's and documented there. This skill covers what is different on the server.
+
+**Where Foldkit's documentation is in this repository:** there is no vendored `repos/foldkit` here. Foldkit's API docs are the doc comments in `node_modules/foldkit/dist/**/*.d.ts` (for example `subscription/keyBindings.d.ts`, `command/index.d.ts`, `dom/dom.d.ts`), and Foldkit UI's in `node_modules/@foldkit/ui/dist`. crease/ui's sources are in the crease repository (`../crease/src/ui`, `src/lib`).
+
+## How to approach the work
+
+- **Start from a working page.** `apps/starter` (generated by `npm run create`) is the smallest complete app; `examples/admin` is a business app (lists, filters, forms, uploads, roles, conflicts, Postgres); `examples/dispatch` is live collaboration (shared state, presence, islands, regions at scale). Pattern-match against them before inventing anything. File pointers by task are in [references/patterns.md](references/patterns.md).
+- **One page = one program.** A page has its own `Model`, `Message`, `ClientMessage`, `flags`, `init`, `update`, `view` and `program`, in `src/app/<page>/page.ts`, mounted in `src/main.ts` with `Hyper.layer(program, { ...options, path })`. Shared state between users lives in services (stores) with a change feed, never in a page.
+- **The architecture is not optional.** update and view stay pure; side effects are Commands; data arriving from outside is a Subscription. No module-level mutable state in pages, no reading the clock or random in update, no `window`/`document` anywhere on the server.
+- **Make it work in a browser, not just in tests.** A page is done when `npm run typecheck`, `npm test` and the browser check (`npm run check` against `npm start`) pass, and you have looked at it.
+
+## A page in brief
+
+```ts
+export const Model = S.Struct({ user: S.String, items: S.Array(Item), draft: S.String, error: S.NullOr(S.String) })
+export const Message = defineMessageUnion({
+  ChangedDraft: { text: S.String },          // typed text: through onInput, never posted as a token
+  Submitted: {},                              // a click/submit: a ClientMessage
+  GotItems: { items: S.Array(Item) },         // from a Subscription: a server fact
+  SucceededAdd: {},                           // a Command result: a server fact
+})
+// What a browser may post directly. Everything else cannot be forged.
+export const ClientMessage = S.Union([Message.Submitted])
+
+export const program: Program<Model, Message, ClientMessage, Flags, Store> = {
+  name: 'items',                              // URL segment and snapshot key: unique per app
+  Model, ClientMessage,
+  flags: request => Effect.gen(function* () { /* authenticate, load */ }),   // PageRedirect / PageNotFound
+  init, update, view, subscriptions,
+  snapshotDeps: model => [model.draft],       // the session's own state; shared data comes back via Subscriptions
+}
+```
+
+The full skeleton with Commands, a Subscription on a store and regions is `apps/starter/src/app/tasks/page.ts`; the API is in [references/api.md](references/api.md).
+
+## Rules that keep pages correct
+
+1. **Bind only `ClientMessage`s in views.** `h.OnClick(Message.X())` renders a token the browser posts back; a Message outside `ClientMessage` fails the render. Command results and Subscription Messages must never be in `ClientMessage`.
+2. **Never trust what the browser posts.** A user can post any `ClientMessage` with any payload: re-check permissions and validate payloads in update (roles, ownership, ids that must exist), exactly as for an HTTP API.
+3. **Typed text goes through handlers.** `onInput`/`onChange` (crease `input`, `h.OnInput(f)`) bind function handlers. Such inputs are *client-owned*: the morph never overwrites what the user types; the server patches the value only when the Model diverges from what the browser sent (for example, clearing the field after save). Do not put typed text into a `ClientMessage`.
+4. **Regions: `region(h, { id, deps, render })`.** Wrap every part of a page that changes independently. `render` returns one element with `h.Id(id)`. `deps` must include every Model value the region's view reads (compared by value); outside production a region whose deps miss something fails to render with the field to add. Nested regions need their parent's deps to cover them. Lists: a region per row, inside a region for the list.
+5. **`shared: true` only for markup identical for every user.** A shared region renders once per deps for all sessions; it may bind Messages only, and must not read the user or any session state (development checks this across sessions).
+6. **Commands run on the server.** No browser globals. Browser effects (focus, scroll, URL replace, navigation) are forwarded via `clientCommands`. Commands whose effects must not happen twice (payments, emails) need idempotency: an event is applied once, but a Command in flight dies with its process. **Before building anything browser-only, read [references/browser.md](references/browser.md):** keyboard shortcuts, focus, drag and drop, menus and dialogs each have a known way.
+7. **The Model must be Schema-encodable.** It is snapshotted as JSON (restarts, failover): no functions, class instances, `File`s or Effects in it. Keep references (ids) and load the rest.
+8. **Flags authenticate and authorize.** Fail with `PageRedirect` (to /login) or `PageNotFound`; set `principal` in options so a session belongs to its user and ends when they sign out.
+9. **Shared data comes from stores with a change feed**, delivered by a Subscription. Build the Message once per change for all sessions with `memoizeLast`; throttle high-churn feeds with `sampleLatest`.
+
+More pitfalls, each found the hard way: [references/gotchas.md](references/gotchas.md). Browser-only behaviour and how to get it: [references/browser.md](references/browser.md).
+
+## Workflow
+
+1. **New app:** `npm run create -- <name> [--title "Title"]` at the monorepo root, then `npm install`. It goes to `apps/<name>` with sign-in, a live page, a store, crease/ui components, Story and HTTP tests and a browser check.
+2. **New page:** copy the shape of `apps/starter/src/app/tasks/page.ts`; add a store service if it has shared data; mount it in `main.ts` with a unique `name` and a `path` (`/things/:id` gives `request.params.id` in flags).
+3. **UI:** crease/ui components are copied in (`src/ui`, behaviour in `src/lib`). More components: copy them from `examples/admin/src/ui` or `examples/dispatch/src/ui` (which have alert, badge, empty, field, native-select, pagination, table, textarea, toggle-group, …) together with their `src/lib` helper, or from the crease repository. Plain `h.*` elements with Tailwind classes are fine too.
+4. **Browser-only behaviour:** check [references/browser.md](references/browser.md) first. Keyboard shortcuts are `keyBindings(h, [...])`, focus is a forwarded Command, drag and drop between server-rendered targets binds natively. Only widgets that need the DOM itself (maps, canvas, rich editors, drag previews) are islands: Foldkit programs running in the browser inside the page.
+5. **Test:**
+   - update with Foldkit's `Story` (pure; resolve Commands by hand), the view with `Scene`;
+   - the page over HTTP with `@hyper-effect/core/testing` (`serve(program, options, store, servicesLayer)`, `openPage`, `postEvent`, `openStream`, `readUntil`, `token`). Pass the page's `path` in `options` for anything but `/`. The stream's first event is the whole page, so wait for text that only appears after your change;
+   - Story tests resolve every Command, forwarded ones included (a focus Command after a shortcut); test the logic with an inner update if a wrapper adds such Commands;
+   - extend `scripts/check.mjs` (Playwright) with every feature: only a browser shows morphs, focus and typing while the page updates.
+6. **Run:** `npm start` (development: markup validation and region checks on; 3–10× slower than production). Measure only with `NODE_ENV=production`.
+
+## Done checklist
+
+- [ ] `npm run typecheck`, `npm test`, `npm run check` pass; no errors in the server log or the browser console.
+- [ ] Every view-bound Message is in `ClientMessage`; update re-checks permissions for each.
+- [ ] Every changing part is a region with complete deps (development renders would fail otherwise; open every state of the page once).
+- [ ] No browser globals in Commands; forwarded browser effects are in `clientCommands`.
+- [ ] Model is plain data; `snapshotDeps` names the session's own state.
+- [ ] Looked at the page in a browser, in two windows if it has shared data.
+
+## Deeper references in the repository
+
+- `README.md` (root): the architecture, correctness mechanisms, security, known limits.
+- `docs/deployment.md`: proxies, compression, several processes, Postgres.
+- `docs/performance.md`: what costs what, and the levers.
+- `packages/core/README.md`: the exports and options.
+- `packages/core/src/*.ts`: the source, with design notes at the top of each file.

package/skill/references/api.md

@@ -0,0 +1,85 @@
+# hyper-effect API
+
+The source is the authority: `packages/core/src/*.ts` (doc comments on every export) and `packages/island/`. This page is the map.
+
+## `@hyper-effect/core`
+
+| Export | What it is |
+|---|---|
+| `layer(program, options)` | Serves a program: the page at `options.path` (plain HTML, works without JavaScript), its SSE stream and its event and upload endpoints under `/_hyper/<program.name>/`. A Layer for `HttpRouter.serve`. |
+| `Program<Model, Message, ClientMessage, Flags, R>` | The page: see below. |
+| `PageRedirect({ location, status? })`, `PageNotFound()` | Fail `flags` with these: redirect (303 by default) or 404. |
+| `PageRequest` | What `flags` gets: `url`, `params` (from `/things/:id`), `visitorId`, `cookies`, `headers`. |
+| `region(h, { id, deps, render, shared? })` | A part of the page re-rendered and re-sent only when `deps` change (by value). |
+| `shared(h, { key, deps, render })` | Markup rendered once per deps for every session and spliced in (Messages only); `region({ shared: true })` is usually what you want. |
+| `keyBindings(h, bindings, { id?, sequenceTimeout? })` | Page-wide keyboard shortcuts, matched in the browser with Foldkit's `keyBindings` grammar and rules (`'C'`, `'Mod+K'`, `'Shift+?'`, `['G', 'M']`; `isEnabled`, `whileTyping`, `preventDefault`, `whenRepeated`). `message` is a ClientMessage, or a function of `{ targetId }` (the focused element's id) run in the session. Only matching keys post. Put it in the view, in a region whose deps cover what the table depends on. |
+| `memoizeLast(f)` | `f` computed once per distinct input and shared: build a shared feed's Message once for all sessions. |
+| `sampleLatest(interval)` | Stream operator: the first element at once, then at most one per interval (presence, counters). |
+| `fileStore(directory)` | Session snapshots in files, each replaced whole. Development and one machine. |
+| `sqlStore({ table?, ttl?, purgeEvery? })` | Session snapshots in SQL through Effect's `SqlClient` (provide `@effect/sql-pg`'s `PgClient.layer`). Several machines. |
+| `metricsRoutes` | `GET /_hyper/metrics` and a CPU profile route. Opt-in, for load tests. |
+| `nodeOfPath(path)` | The process named in a session path, for a router in front of several processes. |
+| `foldkitUiCommands`, `ClientCommands`, `ClientAction` | Forwarding browser-only Commands. |
+
+### `Program`
+
+| Field | Meaning |
+|---|---|
+| `name` | Endpoint segment and snapshot key. Unique per app. |
+| `Model` | Schema of the Model. It is snapshotted as JSON: plain data only. |
+| `ClientMessage` | Schema of the Messages a browser may post as tokens. Views can bind only these. |
+| `flags(request)` | Effectful, request-aware Flags: authenticate, authorize, load. Runs on every page load, and when a session is recreated from its URL after a restart without a snapshot. |
+| `init`, `update`, `view`, `subscriptions` | Foldkit's. `update` returns `{ model, commands? }`. |
+| `onConnectionChange?(isConnected)` | A Message when the page's live connection opens or closes (presence, expensive feeds only while someone looks). |
+| `clientCommands?` | `{ CommandName: args => ClientAction \| undefined }`: Commands not run on the server but performed by the browser after the next morph. Actions: `{ focus: selector }` (unless the user moved focus since they acted), `{ scrollIntoView: selector }`, `{ replaceUrl: url }`, `{ load: url }`, `{ click: selector }`. The Command's result Message is dropped. Foldkit UI's `FocusTab`, `FocusInput`, `FocusButton`, `FocusItems`, `ScrollIntoView` and `ClickItem` are forwarded already (`foldkitUiCommands`); an app's own entry of the same name wins. |
+| `snapshotDeps?(model)` | The session's own state; snapshots are written when it changes. Leave out shared data that Subscriptions bring back. |
+
+### `Options` of `layer`
+
+| Option | Default | Use |
+|---|---|---|
+| `path` | `/` | Path pattern, `/things/:id` |
+| `stylesheets`, `scripts` | none | Linked from the page head (`scripts`: module scripts, such as an islands bundle) |
+| `principal(request)` | none | Who a request acts for (the signed-in user); sessions are bound to it |
+| `contentSecurityPolicy` | on | `{ directives: { 'connect-src': [...] } }` to add sources; `false` for none |
+| `snapshotSecret` | none | Seals snapshots (AES-GCM); a list rotates |
+| `snapshotTtl` | `1 day` | How long a snapshot can restore a session |
+| `durableEvents` | `true` | Answer an event only once it is in the snapshot store (lossless failover) |
+| `compression` | `false` | gzip per stream; ~30× fewer bytes, ~155 kB per open page |
+| `idleTimeout` | `2 minutes` | How long a session without a connection is kept |
+| `node` | none | Process name in session ids, for routing between processes |
+| `trustProxy` | `0` | Number of proxies whose `X-Forwarded-*` count |
+| `allowedOrigins` | `[]` | Extra origins allowed to post events |
+| `limits` | see `server.ts` | Body size, event and page rates, sessions, uploads (`maxUploadBytes` 10 MB, `maxUploadFiles` 10) |
+
+The app must provide a `KeyValueStore` (`fileStore`, `sqlStore`, or `KeyValueStore.layerMemory` in tests) and the services its programs need.
+
+## Event bindings (on `h`, Foldkit's builder, rendered by the server)
+
+- `h.OnClick(Message.X())`, `h.OnSubmit(Message.X())` and other Message-valued events: posted as tokens; the Message must be a `ClientMessage`.
+- `h.OnInput(value => Message.Changed({ value }))`, `h.OnChange(...)`: function handlers kept in the session; the input becomes client-owned. crease's `input({ onInput })` does this.
+- Keyboard handlers (`OnKeyDown` etc.) receive the key and modifiers; `PreventDefault` variants are decided at render time for common keys. `OnPastePreventDefault` and `OnBeforeInputPreventDefault` are not supported.
+- `h.OnFileChange(files => ...)`, `h.OnDropFiles(files => ...)`: the files are uploaded (multipart) and reach update as web `File`s (`foldkit/file`'s `File` schema in the Message).
+- `OnMount` hooks are dropped (they need a browser): use an island.
+
+## `@hyper-effect/core/testing`
+
+| Helper | Use |
+|---|---|
+| `serve(program, options?, store?, services?)` | A web handler for the program; `services` is a Layer providing what the program needs. Pass `{ path: '/things/:id' }` in `options` for a page not at `/`. `dispose()` when done. |
+| `openPage(handler, path?, cookie?)` | A page GET; returns `html`, `sessionId`, `program`, and `cookie` (yours plus the visitor cookie). |
+| `postEvent(handler, page, payload)` | Posts an event: `{ m: token(message), q }` for a ClientMessage, `{ h: handlerId, v: value, q }` for a handler. `q` counts up from 1 per page. |
+| `openStream(handler, page)`, `readUntil(response, text)` | The SSE stream as the browser opens it, read until some text appears. Its first event is the whole page: wait for text only your change produces. |
+| `token(value)` | The token for a Message (`{ _tag: 'Submitted' }`). |
+| `makeStore()`, `waitForSnapshot(store, page)` | An in-memory snapshot store; wait for a session's snapshot. |
+
+Handler ids are in the page: `data-hyper-input="<id>"` on client-owned inputs.
+
+## `@hyper-effect/island`
+
+- `@hyper-effect/island/contract`: `define({ tag, Props, Event })`, shared by server and browser.
+- `@hyper-effect/island`: `Island.view(spec, { id, props, onEvent, class? }, h)` in a server view; put it in a region.
+- `@hyper-effect/island/client`: `register(spec, make)` in the browser bundle.
+- `@hyper-effect/island/vite`: `islandsBuild({ entry, outDir })`; load the bundle with `options.scripts`.
+
+Reference: `examples/dispatch/src/app/dispatch/islands/` and `src/client/islands.ts`.

package/skill/references/browser.md

@@ -0,0 +1,21 @@
+# Browser-only behaviour, and how to get it
+
+A page's update and view run on the server; the browser applies morphs and posts events. Most of what an app needs works that way unchanged. This table lists what does not, or needs a specific tool, with the way that works. Check it before reaching for an island.
+
+| Behaviour | How | Reference |
+|---|---|---|
+| **Keyboard shortcuts for the whole page** (`c`, `/`, Mod+K, `G` then `M`) | `keyBindings(h, [...])` from `@hyper-effect/core`: Foldkit's key grammar, matched in the browser, only a matching key posts. `isEnabled` from the Model; `whileTyping: 'Allow'` for keys that must work in fields (Escape, Mod+K, Mod+Enter). `message` may be a function of `{ targetId }` (the focused element's id) when the field matters (Mod+Enter submits the form you are in). | `apps/starter` (`N`), `apps/linear-clone/src/app/shortcuts/contract.ts` |
+| **Keys with modifiers on one element** (Ctrl+Enter in a textarea) | Not with `OnKeyDownPreventDefault` (probed without modifiers). Use a key binding with `whileTyping: 'Allow'` and a function `message` that checks `targetId`. | clone, `submit` shortcut |
+| **Move focus** (open a panel and focus its input, focus a field after a shortcut) | A Command forwarded with `clientCommands: { FocusX: () => ({ focus: '#id' }) }`. It runs after the next morph, unless the user has moved focus since they acted (then it would steal it). Focus after a click or a key works. | template `FocusNewTask`, clone `FocusElement` |
+| **Scroll an element into view** | `clientCommands: { ScrollX: … => ({ scrollIntoView: '#id' }) }` | clone `ScrollIntoView` |
+| **Address bar** (filters, page number) | `{ replaceUrl }` forwarded; Flags read the URL back | admin `ReplaceUrl` |
+| **Go to another page** | `{ load: url }` forwarded, or a plain link. Every page is a new session; there is no push-history yet (see `docs/design-latency.md`). | admin `LoadUrl` |
+| **Drag and drop between server-rendered targets** (a board) | Works without an island: `OnDragStart`, `OnDragEnter`, `OnDrop` with Messages, and `AllowDrop` on targets. Drag previews, sorting animations and touch dragging need an island. | clone board |
+| **Popover/menu positioning** | CSS anchor positioning (`anchor-name` / `position-anchor`), as crease's menus do. No measuring needed. | crease dropdown-menu |
+| **Foldkit UI Submodels** (tabs, menus, combobox, listbox, select, command) | Run on the server unchanged. Their focus, scroll and click Commands are forwarded automatically (`foldkitUiCommands`), so arrow keys and Enter work. | `docs/compatibility.md` |
+| **Menus with hover highlight** | crease `dropdownMenu({ activateOnHover: false })`: hover in CSS, no request per item. | clone ⋯ menu |
+| **Modal dialogs** (crease dialog, sheet, drawer, alert-dialog, command in a dialog) | Do not open on a server yet (`ShowDialog` needs a browser and reports back). Render an overlay from the Model instead: a fixed panel plus backdrop, shown when the Model says so. | clone create-issue dialog |
+| **`OnMount` hooks, measuring, canvas, maps, rich editors** | An island: a Foldkit program in the browser, with Props in and Events out. | `examples/dispatch` map |
+| **Clipboard copy** | `h.OnCopyText(text)` is bound | — |
+| **File uploads** | `h.OnFileChange` / `h.OnDropFiles`: uploaded, arrive as `File`s | admin images |
+| **Typing, IME, autofill** | Client-owned inputs (`onInput`): handled, including change-only fills | `check:inputs` |

package/skill/references/gotchas.md

@@ -0,0 +1,46 @@
+# Pitfalls
+
+Each of these broke something during hyper-effect's development or experiments. Symptom first, then the fix.
+
+## Views and regions
+
+- **"region … renders differently with the same deps"** (development). The region's view reads something its `deps` miss. Add every Model value it reads, including values used only for classes or labels. The time (`Date.now()`) and randomness are never allowed in a view: put the time in the Model (a tick Subscription) and add it to deps.
+- **"region … keeps its deps while its nested region … changes".** A parent region's deps must cover everything its nested regions read, because an unchanged parent keeps its children without rendering them. Usually: put the list itself in the parent's deps.
+- **"region … must render one element with h.Id(…)".** `render` returns exactly one element, and its id equals the region id.
+- **"placed twice in one render".** Region ids are unique per page. Rows: `task-${task.id}`.
+- **"a view bound a Message that is not a ClientMessage".** Add it to `ClientMessage` if a browser may really send it; otherwise the view must not bind it. Never add Command results or Subscription Messages: anyone could post them.
+- **Shared region "renders differently … for another session".** A `shared: true` region read the user or other session state. Drop `shared`, or take that data out of the region.
+- **Tailwind classes missing.** `src/styles.css` scans `src/` for class names: classes built at runtime (`` `text-${color}` ``) are not found. Write full class names, or map values to complete strings.
+- **A Message returning the same Model** (`{ model }`) renders nothing. That is intended; mutate nothing in place, or the change goes unseen.
+
+## Events and inputs
+
+- **Typed text lost, or overwritten while typing.** Bind inputs with `onInput`/`onChange` handlers (client-owned), never by posting their value in a ClientMessage, and never render a typed field's value from anything but the Model field the handler sets.
+- **The field does not clear after saving.** Set the Model's draft to `''`; the server patches a client-owned input once the Model differs from what the browser sent. A view-only reset does nothing.
+- **Double clicks post twice.** Requests are never cancelled (a cancelled click would be lost). Guard in update: ignore a submit while `isSaving`, and make actions idempotent where they matter.
+- **Not supported:** `OnPastePreventDefault`, `OnBeforeInputPreventDefault`, `OnMount`. Use an island for anything that needs the DOM.
+- **A key with modifiers on an element does nothing** (`OnKeyDownPreventDefault` returning Some only for Ctrl+Enter). Those handlers are probed at render time without modifiers. Use `keyBindings` with `whileTyping: 'Allow'`.
+- **Shortcuts on `<body>` never fire.** Element key handlers only see keys while the element (or a child) has focus, and the view renders inside `<body>`. Use `keyBindings`.
+- **Menus feel slow over a network.** Every hover or arrow key in a server-side Submodel is a round trip. Use `activateOnHover: false` on crease menus; `docs/design-latency.md` has what comes next.
+
+## Commands
+
+- **"Command … needs a browser … skipped on the server".** It touched `window`, `document` or similar. Forward it with `clientCommands` (focus, scrollIntoView, replaceUrl, load) if its result Message is only an acknowledgement, or move the behaviour into an island.
+- **A forwarded Command's result Message never arrives.** By design: forwarded Commands are performed by the browser after the morph, and their result is dropped. Do not forward Commands whose result drives the page (that is why crease's modal dialogs do not open on a server yet).
+- **A forwarded focus does not happen.** It is skipped when the user has moved focus elsewhere since they acted, so it never steals focus. If it never happens, check that the selector exists after the morph and that the Command is in `clientCommands`.
+- **A Command fails and nothing happens.** A failing Command is logged and produces no Message. Catch expected errors inside the Command and turn them into Messages (`FailedSave`, `FailedChange`).
+- **Effects running twice.** Events are applied exactly once, even across retries and process failures; Commands are not re-run on failover, but one in flight when a process dies is lost. Make external effects idempotent (an idempotency key), or record the intent in the Model.
+
+## State and sessions
+
+- **The Model must be plain data,** encodable with `Schema.toCodecJson(Model)`: it is snapshotted for restarts and failover. No `File`s (store them, keep an id), functions, class instances or Effects.
+- **flags run more than once.** On every page load, and when a session is recreated from its URL after a restart without a snapshot (with the stream request's cookies). Keep them free of side effects that must happen once.
+- **Shared data in snapshots.** Leave it out of `snapshotDeps`; the Subscription delivers it again after a restore. Otherwise every shared change rewrites every session's snapshot.
+- **Two layers with the same `program.name`** share endpoints and snapshots. Every page needs its own name, also when one program serves several paths (export a `makeProgram(name)`, as the clone's `issues/page.ts` does).
+- **Sessions end.** A tab that is closed (or loses its connection) for longer than `idleTimeout` (2 minutes) loses its session; reopening loads the page anew from flags. Keep durable state in stores, not in a page's Model.
+
+## Running and measuring
+
+- **Development is 3–10× slower.** Markup validation and the region checks run on every render outside production. Measure with `NODE_ENV=production`.
+- **Inline scripts or styles do not run.** The Content-Security-Policy allows only nonce'd hyper-effect scripts and your `scripts`/`stylesheets`. Add other origins with `contentSecurityPolicy.directives`.
+- **Behind a proxy, live updates stall or posts get 403.** See `docs/deployment.md`: pass the `Host` header (or set `trustProxy` and `X-Forwarded-Host`), and never answer a dead upstream with an error status for session requests.

package/skill/references/patterns.md

@@ -0,0 +1,69 @@
+# Patterns, with working references
+
+Every pattern here runs in the repository and is covered by a browser check. Read the referenced file before writing your own; copy its shape.
+
+## Pages and data
+
+| Need | Reference | Notes |
+|---|---|---|
+| The smallest complete page | `apps/starter/src/app/tasks/page.ts` | Model, Messages, ClientMessage, Commands, Subscription, regions, snapshotDeps |
+| Shared state, live for everyone | `apps/starter/src/app/tasks/store.ts`, `examples/dispatch/src/app/dispatch/store.ts` | A service with a `SubscriptionRef` and `changes` (current value first, then each new one). Pages subscribe; `memoizeLast` builds the Message once for all sessions |
+| The same on Postgres, several processes | `examples/admin/src/app/catalog/postgres.ts` | Writes in a transaction with `pg_notify`; one `LISTEN` per process feeding a version the pages watch |
+| A list with search, filters, sorting, pagination | `examples/admin/src/app/products/list.ts`, `catalog/domain.ts` | The query lives in the Model; `LoadPage` Command; ignore answers to older queries (`sameQuery`); a change feed only signals, each page re-queries |
+| In-page state in the address bar | same, `ReplaceUrl` + `clientCommands` | Flags read the URL back (`queryFromUrl`); the Command is forwarded as `{ replaceUrl }` |
+| A detail page from the URL | `examples/admin/src/app/products/edit.ts` (`/products/:id`), `examples/dispatch/src/app/dispatch/incident.ts` | `request.params.id` in flags; `PageNotFound` for unknown ids |
+| Navigate after an action | `examples/admin/src/app/products/edit.ts`, `LoadUrl` | Forwarded as `{ load: url }` |
+
+## Forms
+
+| Need | Reference | Notes |
+|---|---|---|
+| Typed fields | starter `newTaskForm`, admin `edit.ts` (`ChangedField`) | `input({ onInput })`: client-owned; the draft lives in the Model as strings |
+| Validation with Schema | starter `validateTitle`, admin `domain.ts` `validateDraft` / `fieldErrors` | Validate in update on submit; errors keyed by field name, shown next to the field |
+| Clear the form after saving | starter `SucceededAdd` | Set the draft to `''`: the server patches the client-owned input because the Model now differs from what the browser sent |
+| Server-side errors (taken name, deleted row) | admin `SaveProduct` | The Command catches the error and returns a Message (`FailedSave`); never let a Command fail silently |
+| Edit conflicts | admin `edit.ts`, `StaleRevision` | Save names the revision it started from; the store refuses stale writes; the user can take the other version |
+| Submit right after typing | built in | Unsent typed values travel with every event and are applied first |
+
+## Users
+
+| Need | Reference | Notes |
+|---|---|---|
+| Sign-in | `apps/starter/src/app/auth.ts` | Signed cookie; `requireUser` in flags, `principal` in options |
+| Roles | `examples/admin/src/app/auth.ts`, `edit.ts` `editing(...)` | Hide controls in the view and refuse in update: the browser can post any ClientMessage |
+| Presence (who is here) | `examples/dispatch/src/app/dispatch/board.ts`, `presence` subscription | `onConnectionChange` puts `isConnected` in the Model; the Subscription depends on it and joins only while connected; `sampleLatest` |
+
+## Rendering
+
+| Need | Reference | Notes |
+|---|---|---|
+| Lists that change one row at a time | starter `taskList`, admin `results`, dispatch board rows | A region for the list, a region per row with `deps: [row]` |
+| Rows every user sees alike | dispatch board, `region({ shared: true })` | Rendered once per change for all sessions; Messages only, no user data |
+| crease/ui components | `src/ui/*` + `src/lib/*` in each app | Copy more from `examples/*/src/ui`; they take `(props, h)` |
+| Stateful widgets (tabs, toggle group, menus) | dispatch board `ToggleGroup` (`src/ui/toggle-group.ts`) | Foldkit UI Submodels run on the server unchanged; their focus Commands are forwarded (`foldkitUiCommands`) |
+| Browser-only widgets (maps, canvas, rich editors, drag previews) | `examples/dispatch/src/app/dispatch/islands/`, `src/client/islands.ts`, `vite.islands.config.ts` | An island: a Foldkit program in the browser; Props in, Events out as Messages; put `Island.view` in a region; the bundle via `options.scripts` and a CSP `connect-src` for its sources. Check `browser.md` first: shortcuts, focus and drag and drop need no island |
+
+## Keyboard, focus, menus
+
+| Need | Reference | Notes |
+|---|---|---|
+| Page-wide shortcuts | `apps/starter` (`N`), `apps/linear-clone/src/app/shortcuts/contract.ts` | `keyBindings(h, [...])`; the clone's table has single keys, sequences (`G` `M`), Mod+K and Mod+Enter while typing, and turns list keys off while an overlay is open |
+| Focus after an action | template `FocusNewTask`, clone `FocusElement` (and its `update` wrapper) | A Command forwarded as `{ focus }` |
+| A filterable picker (Linear's status/assignee menus) | `apps/linear-clone/src/app/view/picker.ts` | State in the page Model, items filtered in update, anchored with CSS, keys on its input |
+| A command palette | the same picker in `command` mode; crease `command` rendered inline also works now (Enter is forwarded) | Not inside crease's modal dialog yet |
+| Menus | crease `dropdownMenu` as a Submodel, with `activateOnHover: false` | clone issue page, the menu next to presence |
+| Drag and drop on a board | `apps/linear-clone/src/app/issues/page.ts` (board) | Native drag events with Messages; no island |
+| Inline editing saved on blur | clone issue page description | crease `textarea` with `attributes: [h.OnBlur(...)]` |
+
+## Files
+
+| Need | Reference | Notes |
+|---|---|---|
+| Upload | admin `edit.ts` (`ChoseImage`, `StoreImage`), `catalog/images.ts` | `h.OnFileChange` / `h.OnDropFiles`; the Message carries `File`s; a Command stores them; the Model keeps a reference only. Check the bytes, not the claimed type; serve with `nosniff` |
+
+## Running it
+
+| Need | Reference |
+|---|---|
+| Behind nginx, HTTP/2, compression, several processes, Postgres | `docs/deployment.md` |
+| Load and soak tests | `docs/performance.md`, `tools/perf/` |

package/template/AGENTS.md

@@ -0,0 +1,10 @@
+# Working on {{title}}
+
+This is a hyper-effect app. Before changing it, load the `hyper-effect` skill (and the `foldkit` skill for Foldkit itself); they explain the architecture, the rules and where to find working references.
+
+- Pages are Foldkit programs whose update loop runs on the server. Keep update and view pure; side effects are Commands.
+- Only Messages listed in a page's `ClientMessage` may be bound in its view; typed text goes through `onInput`/`onChange` handlers. Re-check permissions in update.
+- Wrap independently changing parts of a page in `region(h, { id, deps, render })` and list every Model field the region reads in `deps`.
+- Commands run on the server: no `window`, `document` or `localStorage`.
+- Keyboard shortcuts, focus, drag and drop, menus and dialogs: read the skill's `references/browser.md` before building them (shortcuts are `keyBindings(h, [...])`; focus is a forwarded Command).
+- Done means: `npm run typecheck`, `npm test` and `npm run check` (against `npm start`) pass.

package/template/README.md

@@ -0,0 +1,39 @@
+# {{title}}
+
+A hyper-effect app: Foldkit programs whose loop runs on the server, on Effect, with Datastar in the browser.
+
+```sh
+npm start          # builds the CSS, serves http://localhost:4000
+npm run dev        # the same, restarting on changes
+npm test           # update (Foldkit Story) and the page over HTTP
+npm run typecheck
+npm run check      # two people in Chromium against the running server
+```
+
+Sign in with any name. Open a second window with another name to watch changes arrive live. Press `N` to jump to the new-task field.
+
+| File | What it is |
+|---|---|
+| `src/main.ts` | The server: the page's layer, sign-in routes, services, snapshot store |
+| `src/app/tasks/page.ts` | The page: Model, Message, update, view, Commands, Subscription |
+| `src/app/tasks/store.ts` | Shared state with a change feed (in memory; a database in a real app) |
+| `src/app/auth.ts` | Demo sign-in with a signed cookie |
+| `src/ui`, `src/lib` | crease/ui components (button, input, card); copy more from crease |
+| `test/tasks.test.ts` | Story tests of update, HTTP tests of the page |
+| `scripts/check.mjs` | The browser check |
+
+## Adding a page
+
+1. Create `src/app/<page>/page.ts` with `Model`, `Message`, `ClientMessage`, `update`, `view` and `program`, like `src/app/tasks/page.ts`.
+2. Mount it in `src/main.ts`: `Hyper.layer(Page.program, { ...page, path: '/things/:id' })`.
+3. Add Story tests for update and a step to `scripts/check.mjs`.
+
+## Environment
+
+| Variable | Default | Use |
+|---|---|---|
+| `PORT` | `4000` | Listen port |
+| `APP_SECRET` | dev value (required in production) | Signs the sign-in cookie |
+| `HYPER_SNAPSHOT_SECRET` | dev value (required in production) | Seals session snapshots in `.hyper-sessions/` |
+
+Set both secrets outside development.

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+public/styles.css
+.hyper-sessions/

package/template/_package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.0",
+  "private": true,
+  "description": "{{title}}: a hyper-effect app.",
+  "type": "module",
+  "scripts": {
+    "dev": "npm run css && tsx watch src/main.ts",
+    "start": "npm run css && node --import tsx src/main.ts",
+    "css": "tailwindcss -i src/styles.css -o public/styles.css",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "node scripts/check.mjs"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.1.2",
+    "@foldkit/ui": "0.170.0",
+    "@hyper-effect/core": "{{coreVersion}}",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "effect": "4.1.2",
+    "foldkit": "0.170.0",
+    "tailwind-merge": "^3.7.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.1.2",
+    "@tailwindcss/cli": "^4.3.1",
+    "@types/node": "^22.0.0",
+    "playwright": "1.62.1",
+    "tailwindcss": "^4.3.1",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
+  }
+}