create-stitchkit 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -12,6 +12,47 @@ step is overwritten by the next release.
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-09-02
+
+The generated project stops being an empty frame with a to-do at the bottom of
+the page. It ships **one vertical feature**, from schema to transport to UI —
+and it was chosen so that every live primitive Stitchkit gained in 0.75–0.76 is
+there because the feature needs it, not to demonstrate anything.
+
+The demonstration is the second browser tab: post from it, and the first one
+updates without asking. Nothing on that page polls, and nothing refetches after
+a write.
+
+### Added
+
+- **A live board.** `board.list` is a watched read and `board.post` writes to it.
+  Together they use, and only where they are needed:
+  - `defineEvents` — one topic, `board.changed`, declared in `shared` because the
+    server announces it and the browser subscribes to it;
+  - `defineKeyspace` / `openKeyspace` over SQLite — notes are authoritative in
+    memory and durable behind it, so a read in a handler needs no `await` and a
+    restart loses nothing;
+  - `createWatchHub` / `createWatchClient` — every browser asking the same
+    question is **one read** on the server, re-run when the topic says the answer
+    may have changed;
+  - `createTrustFence` — installed on **both** lanes when `TRUSTED_HOSTS` is set,
+    because the Socket.IO lane never reaches a lifecycle hook.
+
+  The comments say which of these to reach for and, more usefully, when not to:
+  a keyspace is for a small bounded set the process wants synchronously, and the
+  moment a thing wants queries, relations or unbounded growth it is a database
+  row and Prisma is already there for it.
+
+- **Two environment variables**, both declared in the one place the project
+  declares variables: `BOARD_STORE_PATH` (defaulted, and the directory is created
+  by the application rather than by whoever deploys it) and `TRUSTED_HOSTS`
+  (unset means no fence, which is honest for a laptop and wrong for anything a
+  network can reach — a fence cannot invent the names it should answer to).
+
+### Changed
+
+- The template now targets `stitchkit` `^0.76.1`, up from `^0.71.0`.
+
 ## [0.5.1] — 2026-09-01
 
 Three findings from someone setting up a new application on the starter from

package/UPGRADING.md

@@ -60,6 +60,49 @@ the first scaffolder release with a migration channel of its own.
 
 ---
 
+## Released migration: 0.6.0
+
+The scaffolder gained a vertical feature. Adopting it in a project you already
+own is optional — nothing breaks if you skip it — but two things are **operator
+steps**, and skipping those with the feature adopted means the API will not
+start.
+
+### 1. The store directory has to be writable
+
+`BOARD_STORE_PATH` defaults to `.data/board.sqlite`, relative to the API role's
+working directory. The application creates the directory itself; what it cannot
+do is make a read-only volume writable.
+
+```bash
+# on the machine, as the user the API runs as
+test -w "$(dirname "${BOARD_STORE_PATH:-.data/board.sqlite}")" || echo "not writable"
+```
+
+If the role runs from a read-only image, point `BOARD_STORE_PATH` at a mounted
+volume instead.
+
+### 2. Decide about the trust fence, on purpose
+
+`TRUSTED_HOSTS` is unset by default, and unset means **no fence**. That is
+correct on a laptop and wrong on anything a network reaches — but a fence cannot
+guess which names your deployment answers to, so it refuses to invent them.
+
+```bash
+# every authority this deployment answers on, comma separated
+TRUSTED_HOSTS=app.internal,app.internal:5181
+```
+
+Set it and the fence is installed on both lanes: HTTP before routing, and the
+realtime handshake, which never reaches a lifecycle hook on either runtime. If
+your browser lives on another origin you already declared it as `CORS_ORIGIN`,
+and the fence reads that one rather than asking you a second time.
+
+### 3. Nothing else
+
+The rest of the feature is code you either copy or do not. The framework range
+moved to `^0.76.1`; if you upgrade the dependency without taking the feature,
+[the framework's own guide](../../docs/guide/upgrading.md) is the one to follow.
+
 ## Released migration: 0.5.0
 
 ### the approval policy names a tool that no longer exists

package/examples/repository/packages/backend/src/surface.snapshot.json

@@ -1,4 +1,36 @@
 [
+  {
+    "service": "board",
+    "action": "list",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
+  {
+    "service": "board",
+    "action": "post",
+    "scope": "public",
+    "hasInput": true,
+    "hasOutput": true,
+    "inputShape": "b1d8eb61c62cafed",
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "POST",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
   {
     "service": "repository",
     "action": "read",

package/examples/repository/packages/backend/src/surface.ts

@@ -1,16 +1,63 @@
 import { env } from '@app/config';
 import { repositoryRealtimeContract } from '@app/shared';
-import { bindRealtimeServer, createSocketIOServer } from 'stitchkit/server';
+import type { TrustFence } from 'stitchkit/server';
+import { bindRealtimeServer, createSocketIOServer, createTrustFence } from 'stitchkit/server';
+import { type BoardRuntime, openBoard } from './lib/board';
+import { bindLive } from './lib/live';
+import { createBoardService } from './transport/board-service';
 import { createRepositoryService } from './transport/repository-service';
 import { createSystemService } from './transport/system-service';
 
+/**
+ * The fence this deployment answers behind, or nothing.
+ *
+ * `trustedHosts` has no default and cannot have one: a fence compares the
+ * authority a request addressed against a list, and it cannot invent the list.
+ * Unset means no fence — honest for a checkout on a laptop, wrong for anything
+ * a network can reach.
+ */
+function createFence(): TrustFence | undefined {
+  if (!env.TRUSTED_HOSTS) return undefined;
+  const browserOrigin = env.CORS_ORIGIN ? [new URL(env.CORS_ORIGIN).host] : [];
+  return createTrustFence({
+    trustedHosts: env.TRUSTED_HOSTS.split(',').map((entry) => entry.trim()),
+    ...(browserOrigin.length > 0 && { trustedOrigins: browserOrigin }),
+    onRefused: (refusal) => {
+      console.warn(
+        `Refused a ${refusal.lane} request: ${refusal.reason} (host ${refusal.host ?? 'absent'})`,
+      );
+    },
+  });
+}
+
 export async function createSurface() {
+  const board: BoardRuntime = await openBoard();
+  const fence = createFence();
+
   const socket = await createSocketIOServer({
     cors: { origin: env.CORS_ORIGIN ?? [] },
+    // The socket's own admission point. `/socket.io/*` never reaches a lifecycle
+    // hook on either runtime, so a fence installed only in `hooks` would leave
+    // open the lane this app pushes its live data over.
+    ...(fence && { allowRequest: fence.allowRequest }),
   });
+
+  // Two bindings over one socket, deliberately. This example's own contract and
+  // the live one are separate declarations with separate event names, and
+  // merging them into a single registry here would mean editing the merge every
+  // time either side gains a topic.
   const realtime = bindRealtimeServer(repositoryRealtimeContract, socket);
+  const live = bindLive(board, socket);
+
   const repositoryService = createRepositoryService((snapshot) =>
     realtime.emit('repository:refreshed', snapshot),
   );
-  return { socket, services: [createSystemService(), repositoryService] };
+
+  return {
+    socket,
+    fence,
+    board,
+    hub: live.hub,
+    services: [createSystemService(), createBoardService(board), repositoryService],
+  };
 }

package/examples/repository/packages/frontend/src/app/[locale]/starter-page.tsx

@@ -4,6 +4,7 @@ import { BrandMark } from '@/components/brand-mark';
 import { RepositorySummary } from '@/components/repository-summary';
 import { LanguageSwitcher, ThemeToggle } from '@/components/system-controls';
 import { buttonVariants } from '@/components/ui';
+import { BoardPanel } from '@/features/board/board-panel';
 import type { AppLocale } from '@/i18n/locales';
 import { Link } from '@/i18n/navigation';
 import { absoluteSiteUrl } from '@/lib/seo/metadata';
@@ -15,6 +16,7 @@ interface StarterPageProps {
   applicationDescription: string;
   heroTitle: string;
   catalogueLabel: string;
+  realtimeOrigin?: string;
   locale: AppLocale;
 }
 
@@ -62,6 +64,7 @@ export async function StarterPage({
   applicationDescription,
   heroTitle,
   catalogueLabel,
+  realtimeOrigin,
   locale,
 }: StarterPageProps) {
   const homeSeo = getSeoPage('home', locale);
@@ -140,6 +143,10 @@ export async function StarterPage({
               </div>
             </div>
 
+            <div className='mt-6 w-full max-w-xl'>
+              <BoardPanel realtimeOrigin={realtimeOrigin} />
+            </div>
+
             <div className='mt-5 w-full'>
               <RepositorySummary />
             </div>

package/examples/repository/packages/shared/src/index.ts

@@ -1,5 +1,8 @@
+export * from './contracts/board';
+export * from './contracts/live';
 export * from './contracts/repository';
 export * from './contracts/system';
 export * from './realtime/repository';
+export * from './schemas/board';
 export * from './schemas/repository';
 export * from './schemas/system';

package/examples/repository/project.json

@@ -105,6 +105,11 @@
         "shape": "string",
         "required": false
       },
+      {
+        "name": "BOARD_STORE_PATH",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "CORS_ORIGIN",
         "shape": "url",
@@ -179,6 +184,11 @@
         "shape": "url",
         "required": false
       },
+      {
+        "name": "TRUSTED_HOSTS",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "WEB_PORT",
         "shape": "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stitchkit",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Create a production-shaped Stitchkit application",
   "license": "MIT",
   "author": "Max Listov <maxlistov@gmail.com>",

package/template/bun.lock

@@ -139,7 +139,7 @@
     },
   },
   "catalog": {
-    "stitchkit": "^0.71.0",
+    "stitchkit": "^0.76.1",
   },
   "packages": {
     "@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.63", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.29", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-D7BogSRg61QfTdr7AEcYn9h0I/e4QHvFXwIV1RW+DZZGJu1wSiX2cH06szZSYyKi7Eat50V4s4J8vggZUEs7eg=="],
@@ -1118,7 +1118,7 @@
 
     "std-env": ["std-env@3.10.0", "", {}, "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg=="],
 
-    "stitchkit": ["stitchkit@0.71.0", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.0.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "grammy": "^1.45.1", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "grammy", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-HXqTD1Sv534rWt+KKJV1Gp535NTRzbGFxNMuRAvo9TzuU0kZxBDF18gu+WexF9O8Z4jkhlfvTjXeRy/oQrnHwA=="],
+    "stitchkit": ["stitchkit@0.76.1", "", { "dependencies": { "ky": "^2.0.2" }, "peerDependencies": { "@modelcontextprotocol/ext-apps": "^1.7.2", "@modelcontextprotocol/server": "^2.0.0", "@openrouter/ai-sdk-provider": "^3.0.0", "@opentelemetry/api": "^1.9.0", "@socket.io/bun-engine": "^0.1.1", "@socket.io/component-emitter": "^3.1.2", "@tanstack/react-query": ">=5", "@types/bun": "^1.3.14", "ai": "^7.0.0", "grammy": "^1.45.1", "react": ">=18", "react-query-kit": "^3.3.3", "socket.io": "^4.8.3", "socket.io-client": "^4.8.3", "srvx": "^0.12.5", "zod": "^4.4.3" }, "optionalPeers": ["@modelcontextprotocol/ext-apps", "@modelcontextprotocol/server", "@openrouter/ai-sdk-provider", "@opentelemetry/api", "@socket.io/bun-engine", "@socket.io/component-emitter", "@tanstack/react-query", "@types/bun", "ai", "grammy", "react", "react-query-kit", "socket.io", "socket.io-client", "srvx"] }, "sha512-+Qmm4CdyWUJJP0MLEQX3M2Ltf0WX5Wi5rEHdZGfWmyIn4SW//x+llQgm516sCyMyJthr9HOaYzxIIP27mBnCmQ=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 
@@ -1190,9 +1190,6 @@
 
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 
-
-
-
     "@prisma/adapter-pg/@types/pg": ["@types/pg@8.21.0", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-AYdtudzabjLZgVgRZmAnU8bAnVUXzuJX2IYHeSIiIHm68olD+LgQYCGWdtcNYnP0uq9c4S4NibVG3Ni7VbKW7Q=="],
 
     "@prisma/adapter-pg/pg": ["pg@8.22.0", "", { "dependencies": { "pg-connection-string": "^2.14.0", "pg-pool": "^3.14.0", "pg-protocol": "^1.15.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.4.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-8wih1vVIBMxoUM2oB4soJsD9tDnDpLv4OXBJ+EJzFsvycD+lfyIreC2gGHq78f8jbLLt+bvlPTFdFZfJkOuzAA=="],

package/template/package.json

@@ -7,7 +7,7 @@
     "packages/*"
   ],
   "catalog": {
-    "stitchkit": "^0.71.0"
+    "stitchkit": "^0.76.1"
   },
   "scripts": {
     "dev": "bun scripts/dev.ts",

package/template/packages/backend/src/index.ts

@@ -3,6 +3,7 @@ import { apiRole, appDeclaration } from '@app/config/declaration';
 import { wrapInRequestContext } from 'stitchkit/observability';
 import {
   bindProcessSignals,
+  composeLifecycleHooks,
   createServer,
   generateOpenApiDocument,
   openApiRoute,
@@ -14,7 +15,7 @@ import { createSurface } from './surface';
 import { onError } from './transport/errors';
 
 async function main(): Promise<void> {
-  const { services, socket } = await createSurface();
+  const { services, socket, fence, board, hub } = await createSurface();
   const mcp = createMcpHandler({
     serverInfo: {
       name: appDeclaration.identity.slug,
@@ -36,7 +37,10 @@ async function main(): Promise<void> {
     port: env.API_PORT,
     hostname: env.BIND_HOST,
     cors: env.CORS_ORIGIN ? { origin: env.CORS_ORIGIN } : undefined,
-    hooks: { onError },
+    // The fence FIRST: hook composition stops at the first hook that answers,
+    // so a fence behind anything that can respond is a fence that sometimes
+    // does not run.
+    hooks: fence ? composeLifecycleHooks(fence.hooks, { onError }) : { onError },
     logging: { format: env.LOG_FORMAT },
     socket,
     rawRoutes: [
@@ -66,6 +70,10 @@ async function main(): Promise<void> {
       // SIGKILL — the one ending that runs no cleanup at all.
       const cleanup = await closeWithinBudget([
         { name: 'MCP', close: () => mcp.close() },
+        // Stops re-reading for browsers that are already gone, then lets the
+        // board finish the writes it accepted and say how many it could not.
+        { name: 'watch hub', close: async () => hub.close() },
+        { name: 'board', close: () => board.close() },
         { name: 'database', close: () => prisma.$disconnect() },
       ]);
       // Say how the drain ended. Without this an operator sees a process that

package/template/packages/backend/src/lib/board.ts

@@ -0,0 +1,99 @@
+import { Database } from 'bun:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { env } from '@app/config';
+import { type Board, boardEvents, type Note, NoteSchema, type PostNote } from '@app/shared';
+import {
+  defineKeyspace,
+  type OpenedKeyspace,
+  openKeyspace,
+  sqliteKeyspaceBackend,
+} from 'stitchkit/application';
+import type { EventPayloads } from 'stitchkit/live';
+import { createEventBus, type EventBus } from 'stitchkit/server';
+
+/**
+ * The board's notes: authoritative in memory, durable behind it.
+ *
+ * A keyspace and not a Prisma model, deliberately, and the boundary is worth
+ * knowing rather than guessing. A keyspace is for a **small, bounded set the
+ * whole process wants synchronously** — read it in a handler without awaiting,
+ * write it and know the write survived. The moment a thing wants queries,
+ * relations, pagination or unbounded growth, it is a database row and this is
+ * the wrong home for it.
+ */
+const notes = defineKeyspace('notes', {
+  schema: NoteSchema,
+  key: (note: Note) => note.id,
+});
+
+/** The board, and the lifecycle its owner drives. */
+export interface BoardRuntime {
+  /** Every announcement this role makes. Subscribed by the watch hub. */
+  readonly events: EventBus<EventPayloads<typeof boardEvents>>;
+  /** Synchronous, from memory. This is what makes a watched read cheap. */
+  read(): Board;
+  post(input: PostNote): Promise<Board>;
+  close(): Promise<void>;
+}
+
+const MOST_RECENT = 50;
+
+export async function openBoard(): Promise<BoardRuntime> {
+  // Closed by the declaration: an undeclared topic is refused rather than
+  // delivered to nobody, and a topic can only be announced by the verb its
+  // declaration chose.
+  const events = createEventBus<EventPayloads<typeof boardEvents>>({
+    topics: boardEvents.topics,
+    onListenerError: (error, event) => {
+      console.error(`Listener for ${event} failed`, error);
+    },
+  });
+
+  // The directory too, not only the file. A starter that requires an operator to
+  // create a folder before it will boot is a starter that fails on the first run
+  // with an error about SQLite rather than about what is missing.
+  mkdirSync(dirname(env.BOARD_STORE_PATH), { recursive: true });
+  const database = new Database(env.BOARD_STORE_PATH, { create: true });
+
+  // Opened directly rather than declared to a kernel, because this role owns
+  // its own lifecycle: it binds its signals and closes what it holds in the
+  // order `cleanup.ts` lists. An application built on `createApplication` would
+  // declare `keyspaceResource(notes, …)` instead and let the graph order it.
+  const opened: OpenedKeyspace<Note> = await openKeyspace(notes, {
+    backend: sqliteKeyspaceBackend(notes, { database }),
+    // After durability and after memory — never before either. A subscriber
+    // woken by this reads immediately, and an announcement that arrived first
+    // would be a wake-up to the previous value.
+    onChanged: (change) => events.emit('board.changed', { noteId: change.key }),
+  });
+
+  function read(): Board {
+    const all = [...opened.keyspace.list()].sort((left, right) =>
+      right.postedAt.localeCompare(left.postedAt),
+    );
+    return { notes: all.slice(0, MOST_RECENT), total: all.length };
+  }
+
+  return {
+    events,
+    read,
+    async post(input) {
+      await opened.keyspace.put({
+        id: crypto.randomUUID(),
+        body: input.body,
+        postedAt: new Date().toISOString(),
+      });
+      // The write resolved, so it is durable and in memory; this read cannot
+      // miss it. The watchers hear about it through the announcement above.
+      return read();
+    },
+    async close() {
+      opened.stopAdmission();
+      await opened.drain();
+      await opened.close();
+      database.close();
+      events.clear();
+    },
+  };
+}

package/template/packages/backend/src/lib/live.ts

@@ -0,0 +1,73 @@
+import { boardContract, liveContract } from '@app/shared';
+import { createWatchHub, type WatchHub } from 'stitchkit/application';
+import { bindRealtimeServer, type RealtimeServerHandle } from 'stitchkit/server';
+import type { BoardRuntime } from './board';
+
+/** What makes the board’s answer stale — the one topic, named once. */
+const INVALIDATED_BY = 'board.changed';
+
+/** A read the browser is allowed to watch. */
+const WATCHABLE = new Set([`${boardContract.meta.prefix}/list`]);
+
+export interface LiveHandle {
+  readonly hub: WatchHub;
+}
+
+export function bindLive(board: BoardRuntime, handle: RealtimeServerHandle): LiveHandle {
+  const realtime = bindRealtimeServer(liveContract, handle, {
+    onRejected: (rejected) => {
+      // A frame that failed its schema is reported where it was refused. Silence
+      // here is how two versions of an application go on talking past each other.
+      console.warn(`Realtime frame refused: ${rejected.event} (${rejected.reason})`);
+    },
+  });
+
+  const hub = createWatchHub({
+    // The hub does not dispatch; it asks the application. One reader for the
+    // watched answer and the plain `GET` alike, so the two cannot disagree.
+    read: async (operation) => {
+      if (operation.action !== 'list') {
+        throw new Error(`${operation.service}.${operation.action} is not readable here`);
+      }
+      return board.read();
+    },
+    watchable: (operation) => WATCHABLE.has(`${operation.service}/${operation.action}`),
+    // The board's list takes no arguments, so its topic is the whole board.
+    // When a read *does* depend on an argument — one conversation of many — the
+    // topic is narrowed with it (`board.changed:${args.id}`), or one change wakes
+    // every watcher of the operation and pays for a read per watcher.
+    invalidatedBy: () => [INVALIDATED_BY],
+    subscribe: (topic, listener) => {
+      // The hub hands back the topics `invalidatedBy` returned, so this is a
+      // narrowing rather than a check — and it refuses rather than quietly
+      // returning a no-op, because an invalidation that silently never fires
+      // is a board that stops updating with nothing to show for it.
+      if (topic !== INVALIDATED_BY) {
+        throw new Error(`The board declares no invalidation topic named ${topic}`);
+      }
+      return board.events.on(topic, listener);
+    },
+    // A browser may watch a handful of questions, not an unbounded number: the
+    // limit is what turns a bug in a page into a refusal instead of a leak.
+    maxWatchesPerSubscriber: 8,
+    // A page that navigates away and back inside the window finds the answer
+    // warm and costs no read.
+    holdMs: 30_000,
+  });
+
+  realtime.onConnection(({ raw, events }) => {
+    const watcher = hub.attach({
+      value: (frame) => events.emit('stitchkit.watch.value', frame),
+      state: (frame) => events.emit('stitchkit.watch.state', frame),
+    });
+    events.on('stitchkit.watch.open', (payload, acknowledge) => {
+      acknowledge(watcher.open(payload.key, payload.args));
+    });
+    events.on('stitchkit.watch.close', (payload) => watcher.close(payload.key));
+    // Every key this connection held is released here. Without it the hub goes
+    // on re-reading for a browser that closed its tab.
+    raw.on('disconnect', () => watcher.detach());
+  });
+
+  return { hub };
+}

package/template/packages/backend/src/surface.snapshot.json

@@ -1,4 +1,36 @@
 [
+  {
+    "service": "board",
+    "action": "list",
+    "scope": "public",
+    "hasInput": false,
+    "hasOutput": true,
+    "inputShape": null,
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "GET",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
+  {
+    "service": "board",
+    "action": "post",
+    "scope": "public",
+    "hasInput": true,
+    "hasOutput": true,
+    "inputShape": "b1d8eb61c62cafed",
+    "outputShape": "ce49fe198eb3412f",
+    "http": [
+      {
+        "method": "POST",
+        "path": "/api/board"
+      }
+    ],
+    "tools": {}
+  },
   {
     "service": "system",
     "action": "status",

package/template/packages/backend/src/surface.ts

@@ -1,13 +1,63 @@
 import { env } from '@app/config';
-import { createSocketIOServer } from 'stitchkit/server';
+import { createSocketIOServer, createTrustFence, type TrustFence } from 'stitchkit/server';
+import { type BoardRuntime, openBoard } from './lib/board';
+import { bindLive } from './lib/live';
+import { createBoardService } from './transport/board-service';
 import { createSystemService } from './transport/system-service';
 
+/**
+ * The fence this deployment answers behind, or nothing.
+ *
+ * `trustedHosts` has no default and cannot have one: a fence can compare the
+ * authority a request addressed against a list, and it cannot invent the list.
+ * Unset means no fence, which is honest for a checkout on a laptop and wrong for
+ * anything a network can reach.
+ *
+ * The browser origin is the one already declared for CORS. They answer different
+ * questions — CORS says what a page may *read*, the fence says which authority
+ * this server agreed to *answer on* — but a deployment that names a cross-origin
+ * browser has named it once, and asking twice is asking for two answers that
+ * disagree.
+ */
+function createFence(): TrustFence | undefined {
+  if (!env.TRUSTED_HOSTS) return undefined;
+  const browserOrigin = env.CORS_ORIGIN ? [new URL(env.CORS_ORIGIN).host] : [];
+  return createTrustFence({
+    trustedHosts: env.TRUSTED_HOSTS.split(',').map((entry) => entry.trim()),
+    ...(browserOrigin.length > 0 && { trustedOrigins: browserOrigin }),
+    onRefused: (refusal) => {
+      console.warn(
+        `Refused a ${refusal.lane} request: ${refusal.reason} (host ${refusal.host ?? 'absent'})`,
+      );
+    },
+  });
+}
+
 export async function createSurface() {
+  const board: BoardRuntime = await openBoard();
+  const fence = createFence();
+
   // An EMPTY allow-list is same-origin: no origin is permitted to open a
   // cross-origin socket, and no browser on this app's own origin needs one.
   // `CORS_ORIGIN` is set only when the browser genuinely lives elsewhere.
   // (Once the workspace targets a Stitchkit release where `cors` itself is
   // optional, this becomes `undefined` and the empty array goes away.)
-  const socket = await createSocketIOServer({ cors: { origin: env.CORS_ORIGIN ?? [] } });
-  return { socket, services: [createSystemService()] };
+  const socket = await createSocketIOServer({
+    cors: { origin: env.CORS_ORIGIN ?? [] },
+    // The socket's own admission point, and the reason the fence has two halves:
+    // `/socket.io/*` never reaches a lifecycle hook on either runtime, so a
+    // fence installed only in `hooks` would leave open the lane this app pushes
+    // its live data over.
+    ...(fence && { allowRequest: fence.allowRequest }),
+  });
+
+  const live = bindLive(board, socket);
+
+  return {
+    socket,
+    fence,
+    board,
+    hub: live.hub,
+    services: [createSystemService(), createBoardService(board)],
+  };
 }

package/template/packages/backend/src/transport/board-service.ts

@@ -0,0 +1,18 @@
+import { type Board, boardContract } from '@app/shared';
+import { implement } from 'stitchkit/server';
+import type { BoardRuntime } from '../lib/board';
+
+/**
+ * The board's two operations.
+ *
+ * Nothing here knows it is watched. `list` is an ordinary handler that reads
+ * memory and returns; the watch hub calls this same implementation when a topic
+ * says the answer may have changed, so a watching browser and a plain `GET` can
+ * never disagree — there is one reader, not two.
+ */
+export function createBoardService(board: BoardRuntime) {
+  return implement(boardContract, {
+    list: (): Board => board.read(),
+    post: ({ input }) => board.post(input),
+  });
+}

package/template/packages/config/src/variables.ts

@@ -73,6 +73,22 @@ const baseVariables = {
    * requiring an origin there would be requiring knowledge of the place.
    */
   CORS_ORIGIN: z.url().optional(),
+  /**
+   * Where the board keeps its notes. A file, so they survive a restart — which
+   * is the only thing that makes the board worth watching rather than a toy.
+   */
+  BOARD_STORE_PATH: z.string().min(1).default('.data/board.sqlite'),
+  /**
+   * The authorities this API answers on, comma-separated — `host` or
+   * `host:port`.
+   *
+   * Set it and the trust fence is installed on BOTH lanes: HTTP before routing,
+   * and the realtime handshake, which never reaches a lifecycle hook on either
+   * runtime. Unset and there is no fence, which is honest for a local checkout
+   * and wrong for anything reachable from a network — a fence cannot invent the
+   * list of names it should answer to.
+   */
+  TRUSTED_HOSTS: z.string().min(1).optional(),
 };
 
 /**

package/template/packages/frontend/src/app/[locale]/page.tsx

@@ -1,6 +1,7 @@
 import { appIdentity } from '@app/config/app-identity';
 import type { Metadata } from 'next';
 import { getTranslations } from 'next-intl/server';
+import { env } from '@/env';
 import { LocaleSchema } from '@/i18n/locales';
 import { createPageMetadata } from '@/lib/seo/metadata';
 import { StarterPage } from './starter-page';
@@ -28,6 +29,7 @@ export default async function Page({ params }: { params: Promise<{ locale: strin
       heroTitle={t('heroTitle')}
       catalogueLabel={t('ui')}
       locale={appLocale}
+      realtimeOrigin={env.PUBLIC_REALTIME_ORIGIN}
     />
   );
 }

package/template/packages/frontend/src/app/[locale]/starter-page.tsx

@@ -3,6 +3,7 @@ import Image from 'next/image';
 import { BrandMark } from '@/components/brand-mark';
 import { LanguageSwitcher, ThemeToggle } from '@/components/system-controls';
 import { buttonVariants } from '@/components/ui';
+import { BoardPanel } from '@/features/board/board-panel';
 import type { AppLocale } from '@/i18n/locales';
 import { Link } from '@/i18n/navigation';
 import { absoluteSiteUrl } from '@/lib/seo/metadata';
@@ -14,6 +15,7 @@ interface StarterPageProps {
   applicationDescription: string;
   heroTitle: string;
   catalogueLabel: string;
+  realtimeOrigin?: string;
   locale: AppLocale;
 }
 
@@ -61,6 +63,7 @@ export async function StarterPage({
   applicationDescription,
   heroTitle,
   catalogueLabel,
+  realtimeOrigin,
   locale,
 }: StarterPageProps) {
   const homeSeo = getSeoPage('home', locale);
@@ -139,8 +142,13 @@ export async function StarterPage({
               </div>
             </div>
 
+            <div className='mt-6 w-full max-w-xl'>
+              <BoardPanel realtimeOrigin={realtimeOrigin} />
+            </div>
+
             <p className='mt-5 text-sm text-muted-foreground'>
-              Add your first vertical feature from schema to transport and UI.
+              One vertical feature, from schema to transport to UI. Open a second tab and post
+              from it — nothing on this page polls.
             </p>
           </section>
         </div>

package/template/packages/frontend/src/features/board/board-live.ts

@@ -0,0 +1,91 @@
+'use client';
+
+import { type Board, BoardSchema, boardContract, liveContract } from '@app/shared';
+import { createClient, createRealtimeClient } from 'stitchkit';
+import { createWatchClient, type WatchStateFrame, watchTransport } from 'stitchkit/live';
+
+/**
+ * One socket and one watch client for the life of the tab.
+ *
+ * Kept in a module local rather than in React state, and that is the whole
+ * point: the server shares one read between everyone asking the same question,
+ * and a client per component would defeat that from the other side. A component
+ * that remounts joins the subscription that exists.
+ */
+let shared: ReturnType<typeof connect> | undefined;
+
+/**
+ * Where the socket dials.
+ *
+ * The page's own origin unless a deployment says otherwise, and "otherwise" is
+ * handed down per request rather than compiled in — a `NEXT_PUBLIC_` value is
+ * substituted at build time, which would freeze one deployment's address into
+ * the artifact. `PUBLIC_REALTIME_ORIGIN` exists because a WebSocket upgrade does
+ * not survive a proxying route handler, so the two roles can share an origin for
+ * HTTP and still need to name the socket's.
+ */
+function connect(realtimeOrigin?: string) {
+  const realtime = createRealtimeClient(liveContract, {
+    url: realtimeOrigin ?? window.location.origin,
+  });
+  realtime.connect();
+  return {
+    realtime,
+    // `watchTransport` is the conversion the framework owns: a bound realtime
+    // client's `on` is generic over its contract, and TypeScript will not relate
+    // that to a transport interface. One call, and no cast in this application.
+    watch: createWatchClient(boardContract, {
+      transport: watchTransport(realtime),
+      // A tab that navigates away and back inside the window paints from memory
+      // and costs no read.
+      holdMs: 30_000,
+    }),
+  };
+}
+
+/** The typed HTTP client, for the one operation that writes. */
+export const boardApi = createClient(boardContract, { baseUrl: '/api' });
+
+export interface BoardWatch {
+  close(): void;
+}
+
+/**
+ * Watch the board.
+ *
+ * `onState` is the honest half and is not optional in practice: `opening` means
+ * subscribed and nothing read yet, which is neither healthy nor broken, and
+ * `unavailable` carries the read's own words rather than a flag. A socket that
+ * drops says so here and resumes on its own when it comes back.
+ */
+export function watchBoard(
+  onValue: (board: Board) => void,
+  onState: (state: WatchStateFrame) => void,
+  realtimeOrigin?: string,
+): BoardWatch {
+  shared ??= connect(realtimeOrigin);
+  const handle = shared.watch.list({});
+  const stop = handle.subscribe({
+    value: (value) => {
+      // Parsed at the boundary rather than asserted. A watched read carries the
+      // operation's output, so a value that fails its own schema means this tab
+      // and the server disagree about the contract — a half-finished deploy, or
+      // a cached bundle from before one. That is worth showing; a cast would
+      // render it as though it were fine and fail somewhere unrelated.
+      const parsed = BoardSchema.safeParse(value);
+      if (!parsed.success) {
+        onState({
+          key: { service: boardContract.meta.prefix, action: 'list', digest: '' },
+          phase: 'unavailable',
+          reason: 'source-error',
+          message:
+            'The board arrived in a shape this page does not know — reload to update it.',
+        });
+        return;
+      }
+      onValue(parsed.data);
+    },
+    state: onState,
+  });
+  return { close: stop };
+}

package/template/packages/frontend/src/features/board/board-panel.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import type { Board } from '@app/shared';
+import { useEffect, useState } from 'react';
+import type { WatchStateFrame } from 'stitchkit/live';
+import {
+  Button,
+  Card,
+  CardContent,
+  CardHeader,
+  CardTitle,
+  Input,
+  Spinner,
+} from '@/components/ui';
+import { boardApi, watchBoard } from './board-live';
+
+/**
+ * The board, live.
+ *
+ * The demonstration is the second tab: open one, post from the other, and the
+ * note appears without this component asking for it. Nothing here polls, and
+ * nothing here refetches after a write — the server re-reads once, for everyone
+ * watching, and pushes the answer.
+ */
+export function BoardPanel({ realtimeOrigin }: { realtimeOrigin?: string }) {
+  const [board, setBoard] = useState<Board>();
+  const [state, setState] = useState<WatchStateFrame>();
+  const [draft, setDraft] = useState('');
+  const [posting, setPosting] = useState(false);
+
+  useEffect(() => {
+    const watch = watchBoard(setBoard, setState, realtimeOrigin);
+    return () => watch.close();
+  }, [realtimeOrigin]);
+
+  async function post(event: React.FormEvent) {
+    event.preventDefault();
+    const body = draft.trim();
+    if (!body || posting) return;
+    setPosting(true);
+    try {
+      // The write returns the board too, so this tab does not wait for its own
+      // announcement to come back around. Every other tab learns from the push.
+      setBoard(await boardApi.post({ body }));
+      setDraft('');
+    } finally {
+      setPosting(false);
+    }
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Board</CardTitle>
+      </CardHeader>
+      <CardContent className='space-y-4'>
+        <form className='flex gap-2' onSubmit={post}>
+          <Input
+            aria-label='Note'
+            maxLength={140}
+            onChange={(event) => setDraft(event.target.value)}
+            placeholder='Say something, then open a second tab'
+            value={draft}
+          />
+          <Button disabled={posting || draft.trim().length === 0} type='submit'>
+            Post
+          </Button>
+        </form>
+
+        <BoardStatus board={board} state={state} />
+
+        <ul className='space-y-2'>
+          {board?.notes.map((note) => (
+            <li className='rounded-md border px-3 py-2 text-sm' key={note.id}>
+              {note.body}
+            </li>
+          ))}
+        </ul>
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * Three states, not two.
+ *
+ * `opening` is subscribed and nothing read yet — early, not broken — and showing
+ * it as a failure tells a reader something is wrong when the truth is that it
+ * has not arrived. `unavailable` shows the read's own words, because "something
+ * went wrong" is the message that helps nobody.
+ */
+function BoardStatus({ board, state }: { board?: Board; state?: WatchStateFrame }) {
+  if (state?.phase === 'unavailable') {
+    return (
+      <p className='text-destructive text-sm'>
+        Not live: {state.message ?? state.reason ?? 'the server stopped answering'}
+      </p>
+    );
+  }
+  if (!board) {
+    return (
+      <p className='flex items-center gap-2 text-muted-foreground text-sm'>
+        <Spinner /> Waiting for the first read…
+      </p>
+    );
+  }
+  return (
+    <p className='text-muted-foreground text-sm'>
+      {board.total} {board.total === 1 ? 'note' : 'notes'}, live
+    </p>
+  );
+}

package/template/packages/shared/src/contracts/board.ts

@@ -0,0 +1,54 @@
+import { createContractFactory } from 'stitchkit';
+import { defineEvents } from 'stitchkit/live';
+import { BoardChangedSchema, BoardSchema, PostNoteSchema } from '../schemas/board';
+
+const { defineContract } = createContractFactory<'public'>({
+  toolExposure: 'explicit',
+});
+
+/**
+ * The board: read it, add to it.
+ *
+ * Two operations, and the interesting one is `list` — it is a **watched read**.
+ * Nothing about that shows up here, which is the point: a watched read is an
+ * ordinary `GET` that the server happens to re-run when something it depends on
+ * changes. The contract stays the contract, and one caller can fetch it once
+ * while another watches it.
+ */
+export const boardContract = defineContract(
+  { prefix: 'board', scope: 'public' },
+  {
+    list: {
+      method: 'GET',
+      path: '/',
+      desc: 'Read the board',
+      output: BoardSchema,
+      expose: ['HTTP'],
+    },
+    post: {
+      method: 'POST',
+      path: '/',
+      desc: 'Add a note to the board',
+      input: PostNoteSchema,
+      output: BoardSchema,
+      expose: ['HTTP'],
+    },
+  },
+);
+
+/**
+ * What the server announces, declared beside what it can be asked.
+ *
+ * One topic, one payload schema, and a delivery mode — `emit`, because an
+ * announcement that the board changed is an observation and nothing waits on it.
+ * The wire name is the prefixed one, `board.changed`, and it is the only name
+ * this topic has: the short key below is where the full one is built.
+ *
+ * Declared in `shared` for the same reason the contract is: the server publishes
+ * it and the browser subscribes to it, and a topic described twice is a topic
+ * that will be published in one shape and parsed in another.
+ */
+export const boardEvents = defineEvents(
+  { prefix: 'board' },
+  { changed: { schema: BoardChangedSchema, mode: 'emit' } },
+);

package/template/packages/shared/src/contracts/live.ts

@@ -0,0 +1,20 @@
+import { toRealtimeContract, watchContract } from 'stitchkit/live';
+import { boardEvents } from './board';
+
+/**
+ * Everything this application says over its one socket.
+ *
+ * Its own announcements, projected from the same declaration both ends read,
+ * plus the protocol a watched read travels on. Declared in `shared` because the
+ * server binds it and the browser binds it, and a contract described twice is a
+ * contract that will be published in one shape and parsed in another — which is
+ * the failure `defineContract` exists to make impossible for requests and this
+ * makes impossible for announcements.
+ */
+export const liveContract = {
+  serverToClient: {
+    ...toRealtimeContract(boardEvents).serverToClient,
+    ...watchContract.serverToClient,
+  },
+  clientToServer: watchContract.clientToServer,
+};

package/template/packages/shared/src/index.ts

@@ -1,2 +1,5 @@
+export * from './contracts/board';
+export * from './contracts/live';
 export * from './contracts/system';
+export * from './schemas/board';
 export * from './schemas/system';

package/template/packages/shared/src/schemas/board.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * One note on the board.
+ *
+ * Small on purpose: the board exists to show a value that several browsers
+ * watch at once, and everything about it that is not that gets in the way.
+ */
+export const NoteSchema = z
+  .object({
+    id: z.uuid(),
+    /** Trimmed and bounded here, so the same limit holds for every transport. */
+    body: z.string().trim().min(1).max(140),
+    postedAt: z.iso.datetime({ offset: true }),
+  })
+  .strict();
+export type Note = z.infer<typeof NoteSchema>;
+
+/** What a reader of the board receives — newest first, and how many there are. */
+export const BoardSchema = z
+  .object({
+    notes: z.array(NoteSchema),
+    total: z.number().int().nonnegative(),
+  })
+  .strict();
+export type Board = z.infer<typeof BoardSchema>;
+
+/** What a writer sends. The server owns `id` and `postedAt`; a client cannot set either. */
+export const PostNoteSchema = z.object({ body: NoteSchema.shape.body }).strict();
+export type PostNote = z.infer<typeof PostNoteSchema>;
+
+/**
+ * The payload of the announcement that the board changed.
+ *
+ * It carries the note's id rather than the note. An announcement says *that*
+ * something changed; the value comes from the read, which is the one place that
+ * decides what a reader is allowed to see. A payload that carried the row would
+ * be a second, unauthorised copy of the answer.
+ */
+export const BoardChangedSchema = z.object({ noteId: NoteSchema.shape.id }).strict();
+export type BoardChanged = z.infer<typeof BoardChangedSchema>;

package/template/project.json

@@ -105,6 +105,11 @@
         "shape": "string",
         "required": false
       },
+      {
+        "name": "BOARD_STORE_PATH",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "CORS_ORIGIN",
         "shape": "url",
@@ -159,6 +164,11 @@
         "shape": "url",
         "required": false
       },
+      {
+        "name": "TRUSTED_HOSTS",
+        "shape": "string",
+        "required": false
+      },
       {
         "name": "WEB_PORT",
         "shape": "integer",