@waniwani/kit 0.1.3 → 0.1.5

package/README.md

@@ -250,6 +250,8 @@ oney/
 │       └── ui.tsx              export default function Component()
 ├── flows/
 │   └── split-payment.ts        export default createFlow(...).compile()   ← SDK
+├── api/
+│   └── cal/slots.ts            export default defineEndpoint({ ..., handler })
 └── lib/                        anything else is just modules
 ```
 
@@ -263,6 +265,7 @@ unwired.
 | `tools/<name>.ts` | one MCP tool | `.ts`, `.tsx` and `.mts` are picked up |
 | `widgets/<name>/` | one MCP tool plus a `ui://` resource | needs `widget.ts` and `ui.tsx` |
 | `flows/<name>.ts` | one MCP tool, registered from the SDK unchanged | whatever `.compile()` returns |
+| `api/<path>.ts` | one HTTP endpoint at `/api/<path>` | for the browser, invisible to the model |
 | anything else | plain modules | the CLI leaves it alone |
 
 The app folder imports `@waniwani/kit`, plus `@waniwani/sdk` when it uses flows,
@@ -327,6 +330,70 @@ export default createFlow({ id: "split_payment", title, description, state })
 `showWidget({ tool: "select-plan" })` names a widget by its folder name, and the
 build check verifies that the folder exists.
 
+### The api/ folder is for the browser
+
+A widget runs in an iframe on another origin, and it can call its own server
+without going through the model at all. Booking a slot, loading a calendar,
+receiving a webhook: `api/` is where those live. The path comes from the file's
+position, the folder name included, so there is nothing to keep in step with the
+`fetch()` on the other side:
+
+```
+api/cal/slots.ts          →  /api/cal/slots
+api/webhooks/stripe.ts    →  /api/webhooks/stripe
+api/cal/index.ts          →  /api/cal
+```
+
+```ts
+// api/cal/slots.ts
+import { defineEndpoint } from "@waniwani/kit";
+import { fetchCalSlots } from "../../lib/cal.js";
+
+export default defineEndpoint({
+  method: "post",
+  handler: async (req, res) => {
+    const { timeZone } = req.body;
+    res.json({ slots: await fetchCalSlots(regionFor(timeZone)) });
+  },
+});
+```
+
+The widget reaches it at the origin the host hands the view, which is the dev
+port locally and the deployed origin inside ChatGPT or Claude:
+
+```tsx
+const apiUrl = (path: string) => `${window.skybridge?.serverUrl ?? ""}${path}`;
+const response = await fetch(apiUrl("/api/cal/slots"), { method: "POST", body });
+```
+
+Four things arrive with every endpoint, so no app writes them:
+
+| | what the runtime does |
+|---|---|
+| **CORS** | on by default, preflight included, advertising the methods `method` declares and no others |
+| **JSON body** | `express.json()`, because the framework installs no parser of its own and `req.body` would be `undefined` |
+| **method guard** | anything outside `method` gets a 405 and an `Allow` header, instead of reaching a handler written for a POST |
+| **errors** | a handler that throws answers JSON with the message, logged as `[waniwani] endpoint "/api/..." failed`, so a `fetch()` waiting on JSON never receives an HTML error page |
+
+`cors: false` and `json: false` opt out of the first two. Leaving `method` off
+accepts every method.
+
+**Reach for a tool instead when the model is the caller.** An endpoint appears in
+no `tools/list`, costs no turn and no tokens, and the model cannot see that it
+happened. That is what suits a calendar the widget paints for itself, and what
+rules it out for anything the model has to reason about or quote back.
+
+Endpoints share the process with `/mcp`, so `lib/` is one set of modules for
+both, and the build check prints what it mounted:
+
+```
+✓ Build check passed — 1 widget, 1 flow, 2 endpoints
+  widget show-book-call
+  flow   demo-qualification
+  api    /api/cal/book
+  api    /api/cal/slots
+```
+
 ### Styling is Tailwind, and only Tailwind
 
 A widget styles itself with utility classes in its `ui.tsx`. There is no
@@ -421,6 +488,7 @@ flowchart LR
         tools["tools/*.ts"]
         widgets["widgets/&lt;name&gt;/<br/>widget.ts + ui.tsx"]
         flows["flows/*.ts"]
+        api["api/**/*.ts"]
     end
 
     subgraph tpl["WaniWani-AI/mcp-distribution-template (public, separate repo)"]
@@ -461,6 +529,76 @@ flowchart LR
 project carrying a `vercel.json`, which is what lets `vercel deploy` inside it
 work with no special support.
 
+### Deploying is a git push
+
+`waniwani build` writes a Vercel Build Output tree inside `.waniwani/`: the
+bundled function, the static assets, the routing config. A git-connected project
+builds that tree itself on push, and the first build writes the config it needs
+into the app repo:
+
+```json
+// vercel.json, generated once, yours to edit afterwards
+{
+  "framework": null,
+  "buildCommand": "waniwani build && rm -rf .vercel/output && cp -R .waniwani/.vercel/output .vercel/output",
+  "routes": [{ "src": "/api(/.*)?", "dest": "/mcp" }]
+}
+```
+
+Each line answers something Vercel would otherwise get wrong.
+
+`framework: null` stops the project's preset from hunting for a dependency the
+repo does not have, which is what produces `No Next.js version detected` on a
+repo holding no framework at all.
+
+The `buildCommand` moves the tree from `.waniwani/`, which is gitignored and
+absent from the clone, up to the one path where Vercel adopts the Build Output
+API and serves the function as built.
+
+The `routes` entry exists because Vercel reserves a root `api/` directory: it
+compiles every file under one into a serverless function of its own, and an
+endpoint module is not a Vercel handler. That entry is emitted ahead of Vercel's
+filesystem layer, so `/api/*` reaches the server the kit built and the functions
+Vercel made are never routed to. Deleting the directory during the build is not
+an alternative, since the file list is read before the build command runs:
+
+```
+Error: File not found: /vercel/path0/api/cal/book.ts
+```
+
+Deploying without a build works too, once `build` has run:
+
+```bash
+cd .waniwani && vercel deploy --prebuilt
+```
+
+Environment variables live on the platform for both, since `.env` is read from
+disk and a hosted build has no such file. A project that sets its variables for
+production alone gets previews with none, which for an app whose flow reads
+`WANIWANI_API_KEY` at import time means a function that fails to boot.
+
+### Secrets live in the app's .env
+
+`.env` and `.env.local` sit next to `waniwani.config.ts`, and every command reads
+them before it runs anything. A variable already exported in the shell or set by
+CI wins over both files, and a hosted deploy sets its variables on the platform
+and reads no file at all.
+
+Loading them this early is what lets a module build its client at import time:
+
+```ts
+// lib/waniwani.ts
+export const wani = waniwani({ apiKey: process.env.WANIWANI_API_KEY });
+```
+
+The generated project runs from `.waniwani/`, one level below the file, and a
+module's imports are evaluated before any line of the module that pulled it in,
+so neither `dotenv/config` nor a load inside generated code arrives in time.
+`waniwani check` reads the same files for the same reason: it imports every
+server-safe module for real, and a flow whose store comes from
+`WANIWANI_API_KEY` would otherwise fail its own build check over a variable
+sitting in the file next to it.
+
 ### What the build check catches
 
 Errors that would otherwise surface as a 500 at request time, or as a widget

package/cli/codegen.mjs

@@ -590,7 +590,7 @@ function templateStyleDomains(template) {
 
 // ------------------------------------------------------------ generated files
 
-function generateServerApp(app, layout, { runtime, styleDomains }) {
+function generateServerApp(app, layout, { runtime, styleDomains, version }) {
 	const from = appFrom(layout);
 
 	const imports = [
@@ -603,6 +603,9 @@ function generateServerApp(app, layout, { runtime, styleDomains }) {
 			(w) => `import widget_${camel(w.name)} from "${from}/widgets/${w.name}/widget.js";`,
 		),
 		...app.flows.map((f) => `import flow_${camel(f.name)} from "${from}/flows/${f.name}.js";`),
+		...app.endpoints.map(
+			(e) => `import endpoint_${camel(e.segments.join("-"))} from "${from}/api/${e.segments.join("/")}.js";`,
+		),
 	].filter(Boolean);
 
 	const list = (items) => (items.length === 0 ? "[]" : `[\n\t\t${items.join(",\n\t\t")},\n\t]`);
@@ -615,10 +618,12 @@ ${imports.join("\n")}
 // on whether this is a generated build or an ejected project.
 loadEnv({ path: ["../.env", ".env"], quiet: true });
 
+// The version the app's package.json carries is the fallback, so a bumped
+// release shows up in the connector UI without a second edit here.
 export const app = {
 	name: config.name,
 	title: config.title,
-	version: config.version ?? "0.0.0",
+	version: config.version ?? ${JSON.stringify(version ?? "0.0.0")},
 	instructions: config.instructions,
 };
 
@@ -627,6 +632,13 @@ export async function registerApp(server: McpServer): Promise<void> {
 		tools: ${list(app.tools.map((t) => `{ name: "${t.name}", def: tool_${camel(t.name)} }`))},
 		widgets: ${list(app.widgets.map((w) => `{ name: "${w.name}", def: widget_${camel(w.name)} }`))},
 		flows: ${list(app.flows.map((f) => `flow_${camel(f.name)}`))},
+		// Served by the same Express app as /mcp, at the path each file's position
+		// produced. For the browser — a widget's fetch — not for the model.
+		endpoints: ${list(
+			app.endpoints.map(
+				(e) => `{ path: "${e.path}", def: endpoint_${camel(e.segments.join("-"))} }`,
+			),
+		)},
 		// Read off the template's ${STYLE_ENTRY}, which every view imports.
 		styleDomains: ${list(styleDomains.map((origin) => `"${origin}"`))},
 	});
@@ -863,6 +875,51 @@ function readProvenance(root) {
 	}
 }
 
+/**
+ * What a git-connected Vercel project needs at the app root, written there when
+ * the app has none.
+ *
+ * The build output lands in `.waniwani/`, which is gitignored and absent from
+ * the clone, so a hosted build has to run the kit itself and move the tree to
+ * the one path where Vercel adopts the Build Output API. Every line here is
+ * about this kit's own layout, which is why the file is generated rather than
+ * taken from the template: the template knows nothing about `waniwani build` or
+ * `.waniwani/`.
+ *
+ * The `routes` entry is the part that is not obvious. Vercel reserves a root
+ * `api/` directory and compiles every file under it into a serverless function
+ * of its own, which for an app folder means one broken function per endpoint
+ * (`defineEndpoint({ ... })` is an object, not a Vercel handler) sitting in the
+ * filesystem layer ahead of the server that actually serves them. A legacy
+ * `routes` entry is emitted before that layer, so `/api/*` reaches the kit's
+ * function and Vercel's own are never routed to. There is no way to stop it
+ * building them: it reads the file list before the build command runs, so a
+ * build that deletes the directory fails with `File not found`, and
+ * `outputDirectory` does not suppress it either.
+ */
+const VERCEL_JSON = {
+	$schema: "https://openapi.vercel.sh/vercel.json",
+	// Otherwise the project's framework preset decides, and a preset looking for a
+	// dependency an app folder does not have fails the build outright.
+	framework: null,
+	buildCommand:
+		"waniwani build && rm -rf .vercel/output && cp -R .waniwani/.vercel/output .vercel/output",
+	// Ahead of Vercel's filesystem layer, which is where its own api/ functions sit.
+	routes: [{ src: "/api(/.*)?", dest: "/mcp" }],
+};
+
+/**
+ * @returns true when the file was written, for the CLI to report
+ */
+function ensureVercelJson(appRoot) {
+	const file = join(appRoot, "vercel.json");
+	// An app that has edited its own deploy config keeps it. Overwriting would
+	// throw away a `maxDuration`, a region, or a cron someone needed.
+	if (existsSync(file)) return false;
+	writeFileSync(file, `${JSON.stringify(VERCEL_JSON, null, 2)}\n`);
+	return true;
+}
+
 /** Keep `.waniwani/` out of the app repo, the way `.next/` is kept out. */
 function ignoreBuildOutput(appRoot) {
 	const file = join(appRoot, ".gitignore");
@@ -978,9 +1035,18 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 		}
 	}
 
+	const appPackageJsonPath = join(app.root, "package.json");
+	const appPackageJson = existsSync(appPackageJsonPath)
+		? JSON.parse(readFileSync(appPackageJsonPath, "utf-8"))
+		: undefined;
+
 	emit(
 		"src/waniwani.ts",
-		generateServerApp(app, layout, { runtime, styleDomains: templateStyleDomains(template) }),
+		generateServerApp(app, layout, {
+			runtime,
+			styleDomains: templateStyleDomains(template),
+			version: appPackageJson?.version,
+		}),
 	);
 	// `src/views/` is shared: the template's own views sit alongside the app's,
 	// so it cannot be wiped. Only the entries a previous build wrote are
@@ -994,11 +1060,6 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 		emit(`src/views/${widget.name}.tsx`, generateWidgetShim(widget, layout));
 	}
 
-	const appPackageJsonPath = join(app.root, "package.json");
-	const appPackageJson = existsSync(appPackageJsonPath)
-		? JSON.parse(readFileSync(appPackageJsonPath, "utf-8"))
-		: undefined;
-
 	const { packageJson, overrides } = generatePackageJson(app, appPackageJson, template, layout);
 
 	emit("tsconfig.json", `${JSON.stringify(generateTsconfig(template, layout), null, 2)}\n`);
@@ -1039,11 +1100,23 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 		)}\n`,
 	);
 
+	let vercelJson = false;
 	if (layoutName === "build") {
 		// A .gitignore inside the output would stop `vercel deploy` uploading
 		// anything, so the ignore goes in the app repo instead.
 		ignoreBuildOutput(app.root);
+		// Same reasoning for the deploy config: what Vercel reads on a git build is
+		// the app repo's root, not the output directory.
+		vercelJson = ensureVercelJson(app.root);
 	}
 
-	return { outDir: root, written, overrides, fromTemplate, moved, manifest: Boolean(manifest) };
+	return {
+		outDir: root,
+		written,
+		overrides,
+		fromTemplate,
+		moved,
+		vercelJson,
+		manifest: Boolean(manifest),
+	};
 }

package/cli/env.mjs

@@ -0,0 +1,37 @@
+/**
+ * The app's `.env`, loaded into this CLI's own environment.
+ *
+ * Two problems make this the only place it can happen.
+ *
+ * The framework runs from the generated project, so `process.cwd()` is
+ * `.waniwani/` and a bare `dotenv/config` looks for `.waniwani/.env` — a file
+ * nobody wrote. The app's `.env` sits one level up, next to `waniwani.config.ts`.
+ *
+ * Loading it from generated code inside that project is too late anyway. ESM
+ * evaluates a module's imports before its body, so by the time any line of
+ * `src/waniwani.ts` runs, every app module it imports has already been
+ * evaluated — and a module that builds an API client at import time has already
+ * read the empty environment and captured it. `createFlow(...).compile()` is the
+ * loud version of this: it throws at import time when `WANIWANI_API_KEY` is
+ * absent.
+ *
+ * Loading here, before anything is spawned, puts the variables in the
+ * environment every child process inherits, whatever order its modules load in.
+ * Hosted deploys set their variables on the platform and never reach this path.
+ */
+
+import { join } from "node:path";
+import dotenv from "dotenv";
+
+const loaded = new Set();
+
+/**
+ * `.env.local` before `.env`: the first file to define a variable wins, and
+ * dotenv never overwrites one already in the environment, so a value exported in
+ * the shell or set by CI outranks both files.
+ */
+export function loadAppEnv(root) {
+	if (loaded.has(root)) return;
+	loaded.add(root);
+	dotenv.config({ path: [join(root, ".env.local"), join(root, ".env")], quiet: true });
+}

package/cli/index.mjs

@@ -19,6 +19,7 @@ import { existsSync, readFileSync, watch } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existingPlumbing, generate } from "./codegen.mjs";
+import { loadAppEnv } from "./env.mjs";
 import { init } from "./init.mjs";
 import { banner, bold, dim, green, printReport, red, yellow } from "./log.mjs";
 import { scanApp } from "./scan.mjs";
@@ -142,7 +143,12 @@ async function prepare(appRoot, flags, { quiet = false } = {}) {
 		console.log(`${yellow("!")} ${dim("GitHub unreachable — using the cached template")}`);
 	}
 
-	const { outDir, overrides, fromTemplate, manifest } = generate(app, { template });
+	const { outDir, overrides, fromTemplate, manifest, vercelJson } = generate(app, { template });
+	// Written into the app's own repo rather than the output, so it is worth a
+	// line even outside debug: it is a tracked file that appeared.
+	if (!quiet && vercelJson) {
+		console.log(`${green("+")} ${bold("vercel.json")} ${dim("— deploy config for a git-connected project")}`);
+	}
 	if (!quiet && DEBUG) {
 		console.log(
 			`${dim(`${fromTemplate.length} files copied`)} ${dim(
@@ -268,7 +274,7 @@ function watchApp(appRoot, template) {
 		}, 120);
 	};
 
-	for (const dir of ["tools", "widgets", "flows"]) {
+	for (const dir of ["tools", "widgets", "flows", "api"]) {
 		const path = join(appRoot, dir);
 		if (existsSync(path)) {
 			watch(path, { recursive: true }, rebuild);
@@ -333,6 +339,12 @@ async function main() {
 		banner(PACKAGE_VERSION);
 	}
 
+	// Before anything is spawned, so every child inherits the app's variables
+	// whatever order its modules evaluate in. `init` has no app to read yet.
+	if (command !== "init") {
+		loadAppEnv(appRoot);
+	}
+
 	if (command === "init") {
 		// Whether a directory was named matters only here: with none, the answer to
 		// the one question decides where the app goes.

package/cli/log.mjs

@@ -150,6 +150,7 @@ export function printReport(app, report) {
 		[app.widgets.length, "widget"],
 		[app.tools.length, "tool"],
 		[app.flows.length, "flow"],
+		[app.endpoints.length, "endpoint"],
 	]
 		.filter(([count]) => count > 0)
 		.map(([count, label]) => `${count} ${label}${count === 1 ? "" : "s"}`);
@@ -165,6 +166,11 @@ export function printReport(app, report) {
 	for (const flow of app.flows) {
 		console.log(`  ${dim("flow  ")} ${flow.name}`);
 	}
+	// The path, not the filename: what a widget writes into a `fetch()` is the
+	// thing worth checking against this line.
+	for (const endpoint of app.endpoints) {
+		console.log(`  ${dim("api   ")} ${endpoint.path}`);
+	}
 	if (report.warnings.length > 0) {
 		console.log("");
 		printGroup(report.warnings, "└", yellow);

package/cli/scan.mjs

@@ -5,6 +5,7 @@
  *   tools/<name>.ts
  *   widgets/<name>/{widget.ts,ui.tsx}
  *   flows/<name>.ts
+ *   api/<path>.ts
  *
  * There is no CSS in that list. Styling is Tailwind, from the distribution
  * template's `src/index.css` — its `@theme` tokens and its `dark` variant — and
@@ -37,6 +38,42 @@ function stripExt(path) {
 	return basename(path, extname(path));
 }
 
+/**
+ * Every code file under `dir`, depth first, as `{ file, segments }` where
+ * `segments` is its path below `dir` with the extension gone.
+ *
+ * `api/` is the one convention folder that nests: an HTTP path has more than
+ * one segment, and the only place it can come from without a registry is the
+ * filesystem.
+ */
+function listTree(dir, trail = []) {
+	if (!existsSync(dir)) return [];
+
+	return readdirSync(dir)
+		.filter((entry) => !entry.startsWith(".") && !entry.startsWith("_"))
+		.flatMap((entry) => {
+			const path = join(dir, entry);
+			if (statSync(path).isDirectory()) {
+				return listTree(path, [...trail, entry]);
+			}
+			if (!CODE_EXT.has(extname(path))) return [];
+			return [{ file: path, segments: [...trail, stripExt(path)] }];
+		});
+}
+
+/**
+ * The URL an endpoint file is served at: its position under the app root,
+ * `/api` included, since that is the folder's name.
+ *
+ * `index` names the directory itself, so `api/cal/index.ts` answers `/api/cal`
+ * — the one place a filename is not taken verbatim, and the convention every
+ * web framework already uses.
+ */
+function endpointPath(segments) {
+	const parts = segments.at(-1) === "index" ? segments.slice(0, -1) : segments;
+	return `/api/${parts.join("/")}`.replace(/\/$/, "") || "/api";
+}
+
 export function scanApp(root) {
 	const configFile = [join(root, "waniwani.config.ts"), join(root, "waniwani.config.js")].find(
 		existsSync,
@@ -57,6 +94,12 @@ export function scanApp(root) {
 		.filter((file) => CODE_EXT.has(extname(file)))
 		.map((file) => ({ name: stripExt(file), file }));
 
+	const endpoints = listTree(join(root, "api")).map(({ file, segments }) => ({
+		path: endpointPath(segments),
+		segments,
+		file,
+	}));
+
 	// The two paths an author is most likely to expect the kit to pick up. It
 	// imports neither, so a file at either one is styling that never reaches the
 	// browser — the kind of silent no-op the build check exists to name.
@@ -65,5 +108,5 @@ export function scanApp(root) {
 		...widgets.map((widget) => join(widget.dir, "styles.css")),
 	].filter(existsSync);
 
-	return { root, configFile, tools, widgets, flows, strayStyles };
+	return { root, configFile, tools, widgets, flows, endpoints, strayStyles };
 }

package/cli/validate.mjs

@@ -8,9 +8,19 @@
 
 import { readFileSync } from "node:fs";
 import { relative } from "node:path";
+import { loadAppEnv } from "./env.mjs";
 
 const NAME_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/;
 
+/**
+ * What may appear in an endpoint path segment. Deliberately narrower than what
+ * a filesystem allows: the segment becomes a URL path, and a file called
+ * `Book Call.ts` would be served at a URL nobody would guess.
+ */
+const SEGMENT_RE = /^[a-zA-Z0-9._-]+$/;
+
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
+
 class Report {
 	constructor(root) {
 		this.root = root;
@@ -113,6 +123,49 @@ function checkStructure(app, report) {
 		seen.set(entry.name, entry);
 	}
 
+	// An endpoint's file position is its URL, so a segment that cannot appear in
+	// a URL is a file served somewhere unguessable, and two files resolving to
+	// one path means the second mount is dead — Express answers from the first.
+	const paths = new Map();
+	// The generator names one import per endpoint, camel-cased from the path, so
+	// two paths that camel-case alike (`api/cal-slots.ts`, `api/cal/slots.ts`)
+	// would emit the same identifier twice and fail in generated code the author
+	// cannot open.
+	const identifiers = new Map();
+	for (const endpoint of app.endpoints) {
+		const where = rel(root, endpoint.file);
+
+		const identifier = endpoint.segments.join("-").replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+		const clash = identifiers.get(identifier);
+		if (clash) {
+			report.error(
+				where,
+				`this path generates the same import name as ${clash}`,
+				"rename one of the two — the generator derives an identifier from the path",
+			);
+		}
+		identifiers.set(identifier, where);
+
+		for (const segment of endpoint.segments) {
+			if (SEGMENT_RE.test(segment)) continue;
+			report.error(
+				where,
+				`"${segment}" cannot be part of a URL path`,
+				"use letters, digits, dashes, dots and underscores — the file's position is the endpoint's path",
+			);
+		}
+
+		const previous = paths.get(endpoint.path);
+		if (previous) {
+			report.error(
+				where,
+				`${endpoint.path} is already served by ${previous}`,
+				"two files resolve to one path — Express answers from the first, so this one never runs",
+			);
+		}
+		paths.set(endpoint.path, where);
+	}
+
 	// Flows point at widgets by name. Catching a typo here beats catching it
 	// when a user is halfway through a conversation.
 	const widgetNames = new Set(app.widgets.map((w) => w.name));
@@ -188,6 +241,27 @@ async function checkModules(app, report) {
 		}
 	}
 
+	for (const endpoint of app.endpoints) {
+		const where = rel(root, endpoint.file);
+		const def = await load(endpoint.file, where, report);
+		if (!def) continue;
+		if (typeof def.handler !== "function") {
+			report.error(
+				where,
+				"endpoint is missing handler()",
+				"export default defineEndpoint({ handler: (req, res) => { ... } })",
+			);
+		}
+		for (const method of def.method ? [def.method].flat() : []) {
+			if (HTTP_METHODS.has(method)) continue;
+			report.error(
+				where,
+				`"${method}" is not an HTTP method`,
+				`one of: ${[...HTTP_METHODS].join(", ")}`,
+			);
+		}
+	}
+
 	for (const flow of app.flows) {
 		const where = rel(root, flow.file);
 		const def = await load(flow.file, where, report);
@@ -238,6 +312,11 @@ async function load(file, where, report) {
 }
 
 export async function validateApp(app) {
+	// The check imports every server-safe module for real, and a module that
+	// builds a client at import time reads the environment while doing it. An app
+	// that runs fine would otherwise fail its own build check over a variable
+	// sitting in the file next to it.
+	loadAppEnv(app.root);
 	const report = new Report(app.root);
 	checkStructure(app, report);
 	// Importing broken modules produces noise on top of structural errors.

package/dist/index.d.ts

@@ -12,7 +12,9 @@
  *   widgets/<name>/widget.ts    export default defineWidget({ ... })
  *   widgets/<name>/ui.tsx       export default function Component() { ... }
  *   flows/<name>.ts             export default createFlow({ ... }).compile()
+ *   api/<path>.ts               export default defineEndpoint({ ... })
  */
+import type { RequestHandler } from "express";
 import type { z } from "zod";
 /** A Zod object shape — `{ name: z.string() }`, not `z.object({ ... })`. */
 export type Shape = z.ZodRawShape;
@@ -103,4 +105,43 @@ export type WidgetDefinition<S extends Shape = Shape> = {
     load?: (input: Infer<S>) => Infer<S> | Promise<Infer<S>>;
 };
 export declare function defineWidget<S extends Shape>(def: WidgetDefinition<S>): WidgetDefinition<S>;
+/**
+ * HTTP methods an endpoint can be restricted to. `undefined` accepts every
+ * method, which is what an Express `use()` mount does.
+ */
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+/**
+ * A plain HTTP endpoint served by the same server as the MCP tools.
+ *
+ * This exists for the browser, not for the model. A widget runs in a
+ * cross-origin iframe and can `fetch()` its own server at
+ * `window.skybridge.serverUrl` — for a booking, a price lookup, a webhook
+ * receiver — and the model never sees the call. Anything the *model* should be
+ * able to reach belongs in `tools/`, not here.
+ *
+ * The path comes from the file's location, `/api` prefix included:
+ * `api/cal/slots.ts` is served at `/api/cal/slots`.
+ */
+export type EndpointDefinition = {
+    /**
+     * Restrict the endpoint to these methods, answering anything else with 405.
+     * Defaults to accepting every method.
+     */
+    method?: HttpMethod | HttpMethod[];
+    /**
+     * Answer cross-origin requests, preflight included. On by default: a widget
+     * is served from a different origin than the server it calls, so an endpoint
+     * without CORS is one the widget cannot reach.
+     */
+    cors?: boolean;
+    /**
+     * Parse a JSON request body into `req.body`. On by default — the framework
+     * installs no body parser of its own, so an endpoint without this reads
+     * `req.body` as `undefined`.
+     */
+    json?: boolean;
+    /** An Express handler. Throwing is safe: the runtime answers 500 and logs. */
+    handler: RequestHandler;
+};
+export declare function defineEndpoint(def: EndpointDefinition): EndpointDefinition;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -12,6 +12,7 @@
  *   widgets/<name>/widget.ts    export default defineWidget({ ... })
  *   widgets/<name>/ui.tsx       export default function Component() { ... }
  *   flows/<name>.ts             export default createFlow({ ... }).compile()
+ *   api/<path>.ts               export default defineEndpoint({ ... })
  */
 export function defineApp(config) {
     return config;
@@ -22,4 +23,7 @@ export function defineTool(def) {
 export function defineWidget(def) {
     return def;
 }
+export function defineEndpoint(def) {
+    return def;
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0CH,MAAM,UAAU,SAAS,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAwBD,MAAM,UAAU,UAAU,CACzB,GAAyB;IAEzB,OAAO,GAAG,CAAC;AACZ,CAAC;AAuCD,MAAM,UAAU,YAAY,CAAkB,GAAwB;IACrE,OAAO,GAAG,CAAC;AACZ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA2CH,MAAM,UAAU,SAAS,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAwBD,MAAM,UAAU,UAAU,CACzB,GAAyB;IAEzB,OAAO,GAAG,CAAC;AACZ,CAAC;AAuCD,MAAM,UAAU,YAAY,CAAkB,GAAwB;IACrE,OAAO,GAAG,CAAC;AACZ,CAAC;AA4CD,MAAM,UAAU,cAAc,CAAC,GAAuB;IACrD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/server.d.ts

@@ -11,7 +11,7 @@
  * hands them to `registerApp()`. Nothing else.
  */
 import { McpServer } from "skybridge/server";
-import type { Shape, ToolHints, WidgetCsp } from "./index.js";
+import type { EndpointDefinition, Shape, ToolHints, WidgetCsp } from "./index.js";
 /**
  * The manifest holds definitions with unrelated schemas side by side, so the
  * handler signatures are widened here. `never` in the parameter position
@@ -50,6 +50,11 @@ export type Manifest = {
         def: AnyWidgetDefinition;
     }>;
     flows: CompiledFlow[];
+    /** HTTP endpoints, each with the path its file position produced. */
+    endpoints?: Array<{
+        path: string;
+        def: EndpointDefinition;
+    }>;
     /**
      * Origins the template's Tailwind entry loads from, read off it at build
      * time. Every view imports that stylesheet, so every widget needs them.

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAiB,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;GAIG;AACH,KAAK,iBAAiB,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CAC/B,CAAC;AAEF,KAAK,mBAAmB,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CACjC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,EAAE,GAAG,CAAC;IAEZ,OAAO,EAAE,GAAG,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACtB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;IACvD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IAC3D,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAqEF;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CA0F3F"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,SAAS,EAAiB,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAc,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9F;;;;GAIG;AACH,KAAK,iBAAiB,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CAC/B,CAAC;AAEF,KAAK,mBAAmB,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CACjC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,MAAM,EAAE,GAAG,CAAC;IAEZ,OAAO,EAAE,GAAG,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACtB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAC;IACvD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAAC;IAC3D,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,qEAAqE;IACrE,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;IAC7D;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AA6IF;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAgG3F"}

package/dist/server.js

@@ -10,6 +10,8 @@
  * against that seam — `src/waniwani.ts` — which imports the app's modules and
  * hands them to `registerApp()`. Nothing else.
  */
+import cors from "cors";
+import express, {} from "express";
 import { McpServer } from "skybridge/server";
 /**
  * The origins a widget may load assets from: its own, plus the ones its
@@ -73,6 +75,74 @@ function widgetError(name, error) {
         ],
     };
 }
+/**
+ * Answer anything outside the declared methods with 405 rather than running the
+ * handler. An endpoint is mounted with `use()`, which matches every method, so
+ * without this a `GET /api/cal/book` would reach a handler written for a POST
+ * body and fail somewhere less obvious.
+ */
+function methodGuard(allowed) {
+    // A preflight never carries the real method, and answering it 405 blocks the
+    // request it was asking about.
+    const pass = new Set([...allowed, "OPTIONS"]);
+    return (req, res, next) => {
+        if (pass.has(req.method))
+            return next();
+        res.setHeader("Allow", allowed.join(", "));
+        res.status(405).json({ error: `${req.method} not allowed` });
+    };
+}
+/**
+ * The last link in every endpoint's chain: a 4-arity middleware, which is how
+ * Express recognises an error handler.
+ *
+ * Scoped to the endpoint's own mount path rather than the app, so it cannot
+ * catch anything the endpoint did not cause. Without it a rejected handler — or
+ * a malformed JSON body, which the parser reports the same way — reaches
+ * Express's default handler and answers an HTML error page to a `fetch()` that
+ * is waiting for JSON.
+ */
+function endpointErrorHandler(path) {
+    return (error, _req, res, next) => {
+        console.error(`[waniwani] endpoint "${path}" failed:`, error);
+        if (res.headersSent)
+            return next(error);
+        // `express.json()` rejects a malformed body with a 400 already on the error.
+        const status = typeof error?.status === "number"
+            ? error.status
+            : 500;
+        res.status(status).json({
+            error: error instanceof Error ? error.message : "Internal server error",
+        });
+    };
+}
+/**
+ * Mount an app's HTTP endpoints on the server's Express app.
+ *
+ * Everything the framework does not do for us is done here, once, rather than
+ * left to each endpoint to remember: CORS (a widget calls from another origin),
+ * a JSON body parser (the framework installs none, so `req.body` would be
+ * `undefined`), the method guard, and the error envelope.
+ */
+function registerEndpoints(server, endpoints) {
+    for (const { path, def } of endpoints) {
+        const methods = def.method ? [def.method].flat().map((m) => m.toUpperCase()) : undefined;
+        const chain = [];
+        // The preflight answer names the methods the guard below actually accepts.
+        // Browsers cache it, so advertising a method that then answers 405 is a
+        // contradiction the widget author has to debug twice.
+        if (def.cors !== false)
+            chain.push(cors(methods ? { methods } : undefined));
+        if (def.json !== false)
+            chain.push(express.json());
+        if (methods)
+            chain.push(methodGuard(methods));
+        chain.push(def.handler, endpointErrorHandler(path));
+        // The error handler's arity is what makes Express treat it as one, and
+        // `use()` is typed for request handlers only.
+        server.use(path, ...chain);
+    }
+}
 /**
  * Register an app's tools, widgets and flows onto a server the template built.
  *
@@ -82,7 +152,12 @@ function widgetError(name, error) {
  * app's own tools sit alongside it.
  */
 export async function registerApp(server, manifest) {
-    const { tools, widgets, flows, styleDomains = [] } = manifest;
+    const { tools, widgets, flows, endpoints = [], styleDomains = [] } = manifest;
+    // Before the tools, because Express matches in registration order and the
+    // framework mounts `/mcp` after this function returns. Nothing here can
+    // shadow it — `/api/...` and `/mcp` do not overlap — but the ordering is the
+    // reason an endpoint is reachable at all.
+    registerEndpoints(server, endpoints);
     // Widgets: one `data` schema drives the input schema, the structured output,
     // and the type the component receives.
     //

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAiB,MAAM,kBAAkB,CAAC;AA+C5D;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,GAA0B,EAAE,YAAsB;IAC1E,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,IAAI,EAAE,CAAC,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,KAAa,EAAE,KAA4B,EAAE,QAAmB;IACpF,MAAM,MAAM,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,CAAC;IACzC,OAAO;QACN,KAAK;QACL,YAAY,EAAE,MAAM,CAAC,QAAQ,IAAI,KAAK;QACtC,eAAe,EAAE,MAAM,CAAC,WAAW,IAAI,KAAK;QAC5C,aAAa,EAAE,MAAM,CAAC,SAAS,IAAI,KAAK;QACxC,cAAc,EAAE,MAAM,CAAC,UAAU,IAAI,KAAK;KAC1C,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,SAAS,UAAU,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC9D,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9D,OAAO,KAA2D,CAAC;IACpE,CAAC;IACD,MAAM,iBAAiB,GAAG,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC;IACnE,OAAO;QACN,iBAAiB;QACjB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACtF,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,IAAY;IACtC,OAAO,OAAO,IAAI,yMAAyM,CAAC;AAC7N,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,KAAc;IAChD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,sBAAsB,IAAI,mBAAmB,EAAE,KAAK,CAAC,CAAC;IACpE,OAAO;QACN,OAAO,EAAE,IAAa;QACtB,OAAO,EAAE;YACR;gBACC,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,OAAO,IAAI,oCAAoC,OAAO,oGAAoG;aAChK;SACD;KACD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAiB,EAAE,QAAkB;IACtE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,QAAQ,CAAC;IAE9D,6EAA6E;IAC7E,uCAAuC;IACvC,EAAE;IACF,4EAA4E;IAC5E,0EAA0E;IAC1E,wEAAwE;IACxE,mEAAmE;IACnE,KAAK,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,OAAO,EAAE,CAAC;QACrC,MAAM,CAAC,YAAY,CAClB;YACC,IAAI;YACJ,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,WAAW,EAAE,GAAG,CAAC,IAAI;YACrB,YAAY,EAAE,GAAG,CAAC,IAAI;YACtB,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;YAClE,IAAI,EAAE;gBACL,SAAS,EAAE,IAAgB;gBAC3B,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,GAAG,EAAE;oBACJ,GAAG,GAAG,CAAC,GAAG;oBACV,eAAe,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC;iBACvD;aACD;SACD,EACD,KAAK,EAAE,KAAK,EAAE,EAAE;YACf,IAAI,CAAC;gBACJ,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAc,CAAC,CAAC,CAAC,CAAC,KAAK,CAG9D,CAAC;gBACF,OAAO;oBACN,iBAAiB,EAAE,IAAI;oBACvB,OAAO,EAAE;wBACR;4BACC,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,IAAa,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC;yBAC7D;qBACD;iBACD,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,OAAO,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;QACF,CAAC,CACD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,KAAK,EAAE,CAAC;QACnC,MAAM,CAAC,YAAY,CAClB;YACC,IAAI;YACJ,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,WAAW,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE;YAC5B,YAAY,EAAE,GAAG,CAAC,MAAM;YACxB,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;SACnE,EACD,KAAK,EAAE,KAAK,EAAE,EAAE;YACf,IAAI,CAAC;gBACJ,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,KAAc,CAAC,CAAC,CAAC;YAClD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,OAAO,CAAC,KAAK,CAAC,oBAAoB,IAAI,WAAW,EAAE,KAAK,CAAC,CAAC;gBAC1D,OAAO;oBACN,OAAO,EAAE,IAAa;oBACtB,OAAO,EAAE;wBACR;4BACC,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,OAAO,IAAI,iBAAiB,OAAO,+EAA+E;yBACxH;qBACD;iBACD,CAAC;YACH,CAAC;QACF,CAAC,CACD,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,6EAA6E;IAC7E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACxE,CAAC;IAED,4EAA4E;IAC5E,4EAA4E;IAC5E,iEAAiE;IACjE,OAAO,MAAM,CAAC;AACf,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waniwani/kit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Build an MCP app as a folder: tools, widgets and flows, with one CLI and one shared server runtime.",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
   },
   "//files": "`src` ships alongside `dist` on purpose: `waniwani eject` vendors the runtime as readable TypeScript, and it reads it out of the installed package.",
   "//dependencies": "tsx, typescript and the @types packages are here rather than in devDependencies because the underlying framework shells out to tsc and tsx by bare name and resolves types from the app repo tree, while declaring none of them. An app repo owns no build config, so this package is the only thing that can put them there. nodemon is the fourth of that set and arrives on its own, as a peer of it.",
+  "//express": "express and cors back the api/ convention: the runtime mounts each endpoint with a JSON body parser and CORS, and an app's handlers are typed against express. Both are already skybridge's own dependencies at these ranges, so declaring them here adds no second copy — it stops an app from depending on a transitive hoist.",
   "files": [
     "dist",
     "src",
@@ -41,12 +42,16 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@tailwindcss/vite": "^4.3.3",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
     "@waniwani/sdk": "^0.19.5",
+    "cors": "^2.8.6",
     "dotenv": "^17.4.1",
+    "express": "^5.2.1",
     "skybridge": "^1.3.5",
     "tailwindcss": "^4.3.3",
     "tsx": "^4.20.6",

package/src/index.ts

@@ -12,8 +12,10 @@
  *   widgets/<name>/widget.ts    export default defineWidget({ ... })
  *   widgets/<name>/ui.tsx       export default function Component() { ... }
  *   flows/<name>.ts             export default createFlow({ ... }).compile()
+ *   api/<path>.ts               export default defineEndpoint({ ... })
  */
 
+import type { RequestHandler } from "express";
 import type { z } from "zod";
 
 /** A Zod object shape — `{ name: z.string() }`, not `z.object({ ... })`. */
@@ -126,3 +128,49 @@ export type WidgetDefinition<S extends Shape = Shape> = {
 export function defineWidget<S extends Shape>(def: WidgetDefinition<S>): WidgetDefinition<S> {
 	return def;
 }
+
+// ------------------------------------------------------------------ endpoints
+
+/**
+ * HTTP methods an endpoint can be restricted to. `undefined` accepts every
+ * method, which is what an Express `use()` mount does.
+ */
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+
+/**
+ * A plain HTTP endpoint served by the same server as the MCP tools.
+ *
+ * This exists for the browser, not for the model. A widget runs in a
+ * cross-origin iframe and can `fetch()` its own server at
+ * `window.skybridge.serverUrl` — for a booking, a price lookup, a webhook
+ * receiver — and the model never sees the call. Anything the *model* should be
+ * able to reach belongs in `tools/`, not here.
+ *
+ * The path comes from the file's location, `/api` prefix included:
+ * `api/cal/slots.ts` is served at `/api/cal/slots`.
+ */
+export type EndpointDefinition = {
+	/**
+	 * Restrict the endpoint to these methods, answering anything else with 405.
+	 * Defaults to accepting every method.
+	 */
+	method?: HttpMethod | HttpMethod[];
+	/**
+	 * Answer cross-origin requests, preflight included. On by default: a widget
+	 * is served from a different origin than the server it calls, so an endpoint
+	 * without CORS is one the widget cannot reach.
+	 */
+	cors?: boolean;
+	/**
+	 * Parse a JSON request body into `req.body`. On by default — the framework
+	 * installs no body parser of its own, so an endpoint without this reads
+	 * `req.body` as `undefined`.
+	 */
+	json?: boolean;
+	/** An Express handler. Throwing is safe: the runtime answers 500 and logs. */
+	handler: RequestHandler;
+};
+
+export function defineEndpoint(def: EndpointDefinition): EndpointDefinition {
+	return def;
+}

package/src/server.ts

@@ -11,8 +11,10 @@
  * hands them to `registerApp()`. Nothing else.
  */
 
+import cors from "cors";
+import express, { type ErrorRequestHandler, type RequestHandler } from "express";
 import { McpServer, type ViewName } from "skybridge/server";
-import type { Shape, ToolHints, WidgetCsp } from "./index.js";
+import type { EndpointDefinition, HttpMethod, Shape, ToolHints, WidgetCsp } from "./index.js";
 
 /**
  * The manifest holds definitions with unrelated schemas side by side, so the
@@ -51,6 +53,8 @@ export type Manifest = {
 	tools: Array<{ name: string; def: AnyToolDefinition }>;
 	widgets: Array<{ name: string; def: AnyWidgetDefinition }>;
 	flows: CompiledFlow[];
+	/** HTTP endpoints, each with the path its file position produced. */
+	endpoints?: Array<{ path: string; def: EndpointDefinition }>;
 	/**
 	 * Origins the template's Tailwind entry loads from, read off it at build
 	 * time. Every view imports that stylesheet, so every widget needs them.
@@ -125,6 +129,78 @@ function widgetError(name: string, error: unknown) {
 	};
 }
 
+/**
+ * Answer anything outside the declared methods with 405 rather than running the
+ * handler. An endpoint is mounted with `use()`, which matches every method, so
+ * without this a `GET /api/cal/book` would reach a handler written for a POST
+ * body and fail somewhere less obvious.
+ */
+function methodGuard(allowed: string[]): RequestHandler {
+	// A preflight never carries the real method, and answering it 405 blocks the
+	// request it was asking about.
+	const pass = new Set([...allowed, "OPTIONS"]);
+
+	return (req, res, next) => {
+		if (pass.has(req.method)) return next();
+		res.setHeader("Allow", allowed.join(", "));
+		res.status(405).json({ error: `${req.method} not allowed` });
+	};
+}
+
+/**
+ * The last link in every endpoint's chain: a 4-arity middleware, which is how
+ * Express recognises an error handler.
+ *
+ * Scoped to the endpoint's own mount path rather than the app, so it cannot
+ * catch anything the endpoint did not cause. Without it a rejected handler — or
+ * a malformed JSON body, which the parser reports the same way — reaches
+ * Express's default handler and answers an HTML error page to a `fetch()` that
+ * is waiting for JSON.
+ */
+function endpointErrorHandler(path: string): ErrorRequestHandler {
+	return (error, _req, res, next) => {
+		console.error(`[waniwani] endpoint "${path}" failed:`, error);
+		if (res.headersSent) return next(error);
+		// `express.json()` rejects a malformed body with a 400 already on the error.
+		const status = typeof (error as { status?: unknown })?.status === "number"
+			? (error as { status: number }).status
+			: 500;
+		res.status(status).json({
+			error: error instanceof Error ? error.message : "Internal server error",
+		});
+	};
+}
+
+/**
+ * Mount an app's HTTP endpoints on the server's Express app.
+ *
+ * Everything the framework does not do for us is done here, once, rather than
+ * left to each endpoint to remember: CORS (a widget calls from another origin),
+ * a JSON body parser (the framework installs none, so `req.body` would be
+ * `undefined`), the method guard, and the error envelope.
+ */
+function registerEndpoints(
+	server: McpServer,
+	endpoints: NonNullable<Manifest["endpoints"]>,
+): void {
+	for (const { path, def } of endpoints) {
+		const methods = def.method ? [def.method].flat().map((m) => m.toUpperCase()) : undefined;
+
+		const chain: Array<RequestHandler | ErrorRequestHandler> = [];
+		// The preflight answer names the methods the guard below actually accepts.
+		// Browsers cache it, so advertising a method that then answers 405 is a
+		// contradiction the widget author has to debug twice.
+		if (def.cors !== false) chain.push(cors(methods ? { methods } : undefined));
+		if (def.json !== false) chain.push(express.json());
+		if (methods) chain.push(methodGuard(methods));
+		chain.push(def.handler, endpointErrorHandler(path));
+
+		// The error handler's arity is what makes Express treat it as one, and
+		// `use()` is typed for request handlers only.
+		server.use(path, ...(chain as RequestHandler[]));
+	}
+}
+
 /**
  * Register an app's tools, widgets and flows onto a server the template built.
  *
@@ -134,7 +210,13 @@ function widgetError(name: string, error: unknown) {
  * app's own tools sit alongside it.
  */
 export async function registerApp(server: McpServer, manifest: Manifest): Promise<McpServer> {
-	const { tools, widgets, flows, styleDomains = [] } = manifest;
+	const { tools, widgets, flows, endpoints = [], styleDomains = [] } = manifest;
+
+	// Before the tools, because Express matches in registration order and the
+	// framework mounts `/mcp` after this function returns. Nothing here can
+	// shadow it — `/api/...` and `/mcp` do not overlap — but the ordering is the
+	// reason an endpoint is reachable at all.
+	registerEndpoints(server, endpoints);
 
 	// Widgets: one `data` schema drives the input schema, the structured output,
 	// and the type the component receives.