@waniwani/kit 0.1.0

package/dist/server.js.map

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

package/dist/web.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The widget-side API.
+ *
+ * A component gets its data from `useWidget(widget)`, typed straight off the
+ * widget's own `data` schema. There is no generated helpers file and no server
+ * type import, so a widget cannot drift from its contract.
+ */
+import type { Infer, Shape, WidgetDefinition } from "./index.js";
+export { mountView, useCallTool, useDisplayMode, useDownload, useFiles, useLayout, useOpenExternal, useRequestClose, useRequestModal, useRequestSize, useSendFollowUpMessage, useSetOpenInAppUrl, useUser, } from "skybridge/web";
+/**
+ * Per-widget state that survives re-renders and is handed back to the host.
+ *
+ * Upstream this is `useViewState`. The name here follows the wire format
+ * instead: what reaches ChatGPT is `openai/widgetCSP`, `openai/widgetDescription`,
+ * and `window.openai.widgetState`. Holding the public vocabulary steady is also
+ * the point of the package — the upstream rename of widgets to views cost app
+ * repos nothing, and it should keep costing them nothing.
+ */
+export { useViewState as useWidgetState } from "skybridge/web";
+export { defineWidget } from "./index.js";
+export type { Infer, Shape, WidgetDefinition } from "./index.js";
+export type UseWidgetResult<S extends Shape> = {
+    /**
+     * The widget's data. Present as soon as the host has the tool input, which
+     * on most hosts is before the server responds — so render optimistically.
+     */
+    data: Infer<S> | undefined;
+    /** The host is still streaming the tool call. */
+    isLoading: boolean;
+    /** The server has responded and `data` is final. */
+    isReady: boolean;
+};
+/**
+ * Read this widget's data.
+ *
+ * @param _widget the widget contract, passed for type inference only
+ */
+export declare function useWidget<S extends Shape>(_widget: WidgetDefinition<S>): UseWidgetResult<S>;
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EACN,SAAS,EACT,WAAW,EACX,cAAc,EACd,WAAW,EACX,QAAQ,EACR,SAAS,EACT,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,OAAO,GACP,MAAM,eAAe,CAAC;AAEvB;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,KAAK,IAAI;IAC9C;;;OAGG;IACH,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC3B,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,KAAK,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAS3F"}

package/dist/web.js

@@ -0,0 +1,35 @@
+/**
+ * The widget-side API.
+ *
+ * A component gets its data from `useWidget(widget)`, typed straight off the
+ * widget's own `data` schema. There is no generated helpers file and no server
+ * type import, so a widget cannot drift from its contract.
+ */
+import { useToolInfo } from "skybridge/web";
+export { mountView, useCallTool, useDisplayMode, useDownload, useFiles, useLayout, useOpenExternal, useRequestClose, useRequestModal, useRequestSize, useSendFollowUpMessage, useSetOpenInAppUrl, useUser, } from "skybridge/web";
+/**
+ * Per-widget state that survives re-renders and is handed back to the host.
+ *
+ * Upstream this is `useViewState`. The name here follows the wire format
+ * instead: what reaches ChatGPT is `openai/widgetCSP`, `openai/widgetDescription`,
+ * and `window.openai.widgetState`. Holding the public vocabulary steady is also
+ * the point of the package — the upstream rename of widgets to views cost app
+ * repos nothing, and it should keep costing them nothing.
+ */
+export { useViewState as useWidgetState } from "skybridge/web";
+export { defineWidget } from "./index.js";
+/**
+ * Read this widget's data.
+ *
+ * @param _widget the widget contract, passed for type inference only
+ */
+export function useWidget(_widget) {
+    const info = useToolInfo();
+    const data = (info.output ?? info.input);
+    return {
+        data,
+        isLoading: !info.isSuccess,
+        isReady: info.isSuccess,
+    };
+}
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../src/web.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACN,SAAS,EACT,WAAW,EACX,cAAc,EACd,WAAW,EACX,QAAQ,EACR,SAAS,EACT,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,OAAO,GACP,MAAM,eAAe,CAAC;AAEvB;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAe1C;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAkB,OAA4B;IACtE,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAyB,CAAC;IAEjE,OAAO;QACN,IAAI;QACJ,SAAS,EAAE,CAAC,IAAI,CAAC,SAAS;QAC1B,OAAO,EAAE,IAAI,CAAC,SAAS;KACvB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@waniwani/kit",
+  "version": "0.1.0",
+  "description": "Build an MCP app as a folder: tools, widgets, flows and docs, with one CLI and one shared server runtime.",
+  "type": "module",
+  "bin": {
+    "waniwani": "cli/index.mjs"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "default": "./dist/web.js"
+    }
+  },
+  "//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.",
+  "files": [
+    "dist",
+    "src",
+    "cli"
+  ],
+  "//README.md": "Written by `scripts/sync-readme.mjs` from the repo root README, which is this package's documentation, and gitignored. npm packs any README.md it finds next to the manifest whatever `files` says.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@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",
+    "dotenv": "^17.4.1",
+    "skybridge": "^1.3.5",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.20.6",
+    "typescript": "^6.0.2",
+    "vite": "^8.1.5"
+  },
+  "devDependencies": {
+    "@skybridge/devtools": "^1.2.7"
+  },
+  "//optionalDependencies": "cloudflared is what `waniwani tunnel` runs, and its install step fetches a platform binary. Every other command works without it, so a CI image or a container build installing with --omit=optional skips the download and still gets a working CLI.",
+  "optionalDependencies": {
+    "cloudflared": "^0.7.1"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19",
+    "zod": "^4"
+  },
+  "//repository": "`directory` is not decoration: `npm publish --provenance` reads this field to bind the published tarball to the workflow run that built it, and the attestation is rejected if it does not resolve.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WaniWani-AI/kit.git",
+    "directory": "packages/kit"
+  },
+  "keywords": [
+    "mcp",
+    "waniwani",
+    "mcp-server",
+    "mcp-app",
+    "framework",
+    "cli",
+    "widgets",
+    "tools",
+    "flows",
+    "skybridge"
+  ],
+  "author": "Waniwani",
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+/**
+ * The Waniwani MCP authoring API.
+ *
+ * This is everything an app author imports. There is no server bootstrap, no
+ * transport, no MCP wiring, no build config in an app repo — the runtime owns
+ * all of it (see `./server.ts`) and the CLI generates the glue (see `../cli/`).
+ *
+ * An app is a folder:
+ *
+ *   waniwani.config.ts          defineApp({ ... })
+ *   tools/<name>.ts             export default defineTool({ ... })
+ *   widgets/<name>/widget.ts    export default defineWidget({ ... })
+ *   widgets/<name>/ui.tsx       export default function Component() { ... }
+ *   flows/<name>.ts             export default createFlow({ ... }).compile()
+ *   docs/<slug>.md              searchable knowledge
+ */
+
+import type { z } from "zod";
+
+/** A Zod object shape — `{ name: z.string() }`, not `z.object({ ... })`. */
+export type Shape = z.ZodRawShape;
+
+/** The TypeScript type a `Shape` describes. */
+export type Infer<S extends Shape> = z.infer<z.ZodObject<S>>;
+
+/**
+ * Behavioural hints handed to the host LLM. The runtime translates these into
+ * MCP `annotations` and always fills in the `title` that Claude's Connectors
+ * Directory requires, so an app repo cannot get that wrong.
+ */
+export type ToolHints = {
+	/** The tool only reads. Defaults to `true` for widgets, `false` for tools. */
+	readOnly?: boolean;
+	/** The tool can destroy data. */
+	destructive?: boolean;
+	/** The tool reaches out to the open internet. */
+	openWorld?: boolean;
+	/** Calling twice with the same input has the same effect as calling once. */
+	idempotent?: boolean;
+};
+
+// ---------------------------------------------------------------- app config
+
+export type AppConfig = {
+	/** MCP server name, e.g. `oney-split-payment`. */
+	name: string;
+	/** Shown to humans in connector UIs. */
+	title?: string;
+	/** Defaults to the app `package.json` version. */
+	version?: string;
+	/**
+	 * Server-level instructions handed to the host LLM once, before any tool
+	 * call. Tone, guardrails, what this app is for.
+	 */
+	instructions?: string;
+};
+
+export function defineApp(config: AppConfig): AppConfig {
+	return config;
+}
+
+// ---------------------------------------------------------------------- tools
+
+/**
+ * What a tool handler may return. A string becomes the model-facing text; an
+ * object becomes `structuredContent` plus a JSON text fallback. Returning a
+ * full MCP `CallToolResult` is still allowed for the rare tool that needs it.
+ */
+export type ToolResult =
+	| string
+	| Record<string, unknown>
+	| { content: Array<{ type: "text"; text: string }>; structuredContent?: Record<string, unknown> };
+
+export type ToolDefinition<S extends Shape = Shape, R extends ToolResult = ToolResult> = {
+	title: string;
+	/** LLM-facing. When to call this, and what it does. */
+	description: string;
+	input?: S;
+	output?: Shape;
+	hints?: ToolHints;
+	run: (input: Infer<S>) => R | Promise<R>;
+};
+
+export function defineTool<S extends Shape, R extends ToolResult>(
+	def: ToolDefinition<S, R>,
+): ToolDefinition<S, R> {
+	return def;
+}
+
+// -------------------------------------------------------------------- widgets
+
+export type WidgetCsp = {
+	/** Domains the widget may `fetch()`. */
+	connectDomains?: string[];
+	/** Domains the widget may load images/fonts/scripts from. */
+	resourceDomains?: string[];
+};
+
+/**
+ * A widget contract. This file is imported by *both* the server and the
+ * browser bundle, so it must stay free of React and CSS — the component lives
+ * next to it in `ui.tsx`.
+ *
+ * `data` is the single schema for the widget: it is the tool's input schema,
+ * its output schema, and the type `useWidget()` hands the component. One
+ * schema, so server and UI cannot drift.
+ */
+export type WidgetDefinition<S extends Shape = Shape> = {
+	title: string;
+	/** LLM-facing. When to show this widget, and how to frame it. */
+	description: string;
+	data: S;
+	hints?: ToolHints;
+	csp?: WidgetCsp;
+	/**
+	 * Text handed to the model alongside the rendered widget. Use it to tell
+	 * the model what NOT to repeat, and what to wait for.
+	 */
+	llmText?: (data: Infer<S>) => string;
+	/**
+	 * Optional server-side loader, for widgets whose data comes from an API
+	 * rather than from the model. Defaults to echoing the input through.
+	 */
+	load?: (input: Infer<S>) => Infer<S> | Promise<Infer<S>>;
+};
+
+export function defineWidget<S extends Shape>(def: WidgetDefinition<S>): WidgetDefinition<S> {
+	return def;
+}
+
+// ----------------------------------------------------------------------- docs
+
+/** A `docs/<slug>.md` file, parsed at build time and inlined into the bundle. */
+export type DocEntry = {
+	slug: string;
+	title: string;
+	body: string;
+};

package/src/server.ts

@@ -0,0 +1,285 @@
+/**
+ * The shared MCP runtime.
+ *
+ * Every Waniwani MCP app runs this exact code. App repos contain no server
+ * bootstrap, so a runtime fix is one package bump away for all of them — no
+ * 30-repo sweep, no per-repo verification.
+ *
+ * The server itself belongs to the distribution template, which constructs it,
+ * registers whatever tools it ships, and runs it. The CLI generates one file
+ * against that seam — `src/waniwani.ts` — which imports the app's modules and
+ * hands them to `registerApp()`. Nothing else.
+ */
+
+import { McpServer, type ViewName } from "skybridge/server";
+import { z } from "zod";
+import type { DocEntry, 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
+ * accepts any concrete handler; the call sites cast back.
+ */
+type AnyToolDefinition = {
+	title: string;
+	description: string;
+	input?: Shape;
+	output?: Shape;
+	hints?: ToolHints;
+	run: (input: never) => unknown;
+};
+
+type AnyWidgetDefinition = {
+	title: string;
+	description: string;
+	data: Shape;
+	hints?: ToolHints;
+	csp?: WidgetCsp;
+	llmText?: (data: never) => string;
+	load?: (input: never) => unknown;
+};
+
+/** A flow compiled by `createFlow(...).compile()` from `@waniwani/sdk/mcp`. */
+export type CompiledFlow = {
+	name: string;
+	// biome-ignore lint/suspicious/noExplicitAny: the SDK's own tool config shape
+	config: any;
+	// biome-ignore lint/suspicious/noExplicitAny: the SDK's own handler shape
+	handler: any;
+};
+
+export type Manifest = {
+	tools: Array<{ name: string; def: AnyToolDefinition }>;
+	widgets: Array<{ name: string; def: AnyWidgetDefinition }>;
+	flows: CompiledFlow[];
+	docs: DocEntry[];
+	/**
+	 * Origins the template's Tailwind entry loads from, read off it at build
+	 * time. Every view imports that stylesheet, so every widget needs them.
+	 */
+	styleDomains?: string[];
+};
+
+/**
+ * The origins a widget may load assets from: its own, plus the ones its
+ * stylesheet needs.
+ *
+ * A host that enforces the widget CSP drops undeclared requests silently — a
+ * blocked webfont is not an error, just a fallback face — so the base
+ * stylesheet's origins are added for every widget rather than left to each app
+ * to remember. An app's own `csp` is additive, never overwritten.
+ */
+function resourceDomains(csp: WidgetCsp | undefined, styleDomains: string[]) {
+	const merged = [...new Set([...(csp?.resourceDomains ?? []), ...styleDomains])];
+	return merged.length > 0 ? merged : undefined;
+}
+
+/**
+ * Translate `hints` into MCP annotations. `title` is always present because
+ * Claude's Connectors Directory rejects tools without one.
+ */
+function annotations(title: string, hints: ToolHints | undefined, defaults: ToolHints) {
+	const merged = { ...defaults, ...hints };
+	return {
+		title,
+		readOnlyHint: merged.readOnly ?? false,
+		destructiveHint: merged.destructive ?? false,
+		openWorldHint: merged.openWorld ?? false,
+		idempotentHint: merged.idempotent ?? false,
+	};
+}
+
+/** Normalise whatever a tool handler returned into an MCP `CallToolResult`. */
+function toolResult(value: unknown) {
+	if (typeof value === "string") {
+		return { content: [{ type: "text" as const, text: value }] };
+	}
+	if (value && typeof value === "object" && "content" in value) {
+		return value as { content: Array<{ type: "text"; text: string }> };
+	}
+	const structuredContent = (value ?? {}) as Record<string, unknown>;
+	return {
+		structuredContent,
+		content: [{ type: "text" as const, text: JSON.stringify(structuredContent, null, 2) }],
+	};
+}
+
+/**
+ * Default model-facing text for a widget. Widgets render their own detail, so
+ * the model is told to stop narrating it — the single most common cause of a
+ * widget being read aloud twice.
+ */
+function defaultWidgetText(name: string) {
+	return `The ${name} widget is now rendered for the user. It displays all the detail itself — do NOT list or repeat its contents in text. Acknowledge it in one short sentence, then wait for the user to interact with it.`;
+}
+
+function widgetError(name: string, error: unknown) {
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`[waniwani] widget "${name}" failed to load:`, error);
+	return {
+		isError: true as const,
+		content: [
+			{
+				type: "text" as const,
+				text: `The ${name} widget could not load its data (${message}). Tell the user something went wrong on our side and offer to try again — do not invent the data.`,
+			},
+		],
+	};
+}
+
+function registerDocsTool(server: McpServer, docs: DocEntry[]) {
+	const corpus = docs.map((doc) => ({
+		...doc,
+		haystack: `${doc.title}\n${doc.body}`.toLowerCase(),
+	}));
+
+	server.registerTool(
+		{
+			name: "search_docs",
+			title: "Search the documentation",
+			description:
+				"Search this product's documentation and answer general questions — pricing, eligibility, policies, how things work. Always search before answering, and answer only from what comes back. Never invent facts that are not in the results.",
+			inputSchema: { question: z.string().describe("The user's question, in their own words.") },
+			outputSchema: {
+				results: z.array(z.object({ slug: z.string(), title: z.string(), body: z.string() })),
+			},
+			annotations: annotations("Search the documentation", undefined, { readOnly: true }),
+		},
+		async ({ question }) => {
+			const terms = question
+				.toLowerCase()
+				.split(/[^a-z0-9]+/)
+				.filter((term) => term.length > 2);
+
+			const results = corpus
+				.map((doc) => ({
+					doc,
+					score: terms.reduce((sum, term) => sum + (doc.haystack.includes(term) ? 1 : 0), 0),
+				}))
+				.filter(({ score }) => score > 0)
+				.sort((a, b) => b.score - a.score)
+				.slice(0, 3)
+				.map(({ doc }) => ({ slug: doc.slug, title: doc.title, body: doc.body }));
+
+			if (results.length === 0) {
+				const text = "Nothing in the documentation covers that question.";
+				return { structuredContent: { results: [] }, content: [{ type: "text" as const, text }] };
+			}
+
+			return {
+				structuredContent: { results },
+				content: [
+					{
+						type: "text" as const,
+						text: results.map((r) => `## ${r.title}\n${r.body}`).join("\n\n---\n\n"),
+					},
+				],
+			};
+		},
+	);
+}
+
+/**
+ * Register an app's tools, widgets, flows, and docs onto a server the template
+ * built.
+ *
+ * The template owns construction, its own tools, `withWaniwani`, and `run()`.
+ * This adds to that server rather than replacing it, so a tool the template
+ * ships reaches every app built on it — one publish, not thirty edits — and an
+ * app's own tools sit alongside it.
+ */
+export async function registerApp(server: McpServer, manifest: Manifest): Promise<McpServer> {
+	const { tools, widgets, flows, docs, styleDomains = [] } = manifest;
+
+	// Widgets: one `data` schema drives the input schema, the structured output,
+	// and the type the component receives.
+	//
+	// A widget is a tool with a view attached. The view's component name is the
+	// widget's folder name, which is also the name of the entry the generator
+	// writes into `src/views/` — one name, from the filesystem, so a widget
+	// cannot be registered against a component that was never bundled.
+	for (const { name, def } of widgets) {
+		server.registerTool(
+			{
+				name,
+				title: def.title,
+				description: def.description,
+				inputSchema: def.data,
+				outputSchema: def.data,
+				annotations: annotations(def.title, def.hints, { readOnly: true }),
+				view: {
+					component: name as ViewName,
+					description: def.description,
+					csp: {
+						...def.csp,
+						resourceDomains: resourceDomains(def.csp, styleDomains),
+					},
+				},
+			},
+			async (input) => {
+				try {
+					const data = (def.load ? await def.load(input as never) : input) as Record<
+						string,
+						unknown
+					>;
+					return {
+						structuredContent: data,
+						content: [
+							{
+								type: "text" as const,
+								text: def.llmText?.(data as never) ?? defaultWidgetText(name),
+							},
+						],
+					};
+				} catch (error) {
+					return widgetError(name, error);
+				}
+			},
+		);
+	}
+
+	for (const { name, def } of tools) {
+		server.registerTool(
+			{
+				name,
+				title: def.title,
+				description: def.description,
+				inputSchema: def.input ?? {},
+				outputSchema: def.output,
+				annotations: annotations(def.title, def.hints, { readOnly: false }),
+			},
+			async (input) => {
+				try {
+					return toolResult(await def.run(input as never));
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					console.error(`[waniwani] tool "${name}" failed:`, error);
+					return {
+						isError: true as const,
+						content: [
+							{
+								type: "text" as const,
+								text: `The ${name} tool failed (${message}). Tell the user it did not work and offer to retry — do not invent a result.`,
+							},
+						],
+					};
+				}
+			},
+		);
+	}
+
+	// Flows arrive from the SDK shaped for the MCP SDK's `(name, config, handler)`
+	// call, which the framework replaced with a single config carrying the name.
+	for (const flow of flows) {
+		server.registerTool({ ...flow.config, name: flow.name }, flow.handler);
+	}
+
+	if (docs.length > 0) {
+		registerDocsTool(server, docs);
+	}
+
+	// `withWaniwani` is deliberately not called here. It wraps every registered
+	// handler in place, so it has to run after the last registration — which is
+	// the template's, not this function's. `src/server.ts` calls it.
+	return server;
+}

package/src/web.tsx

@@ -0,0 +1,68 @@
+/**
+ * The widget-side API.
+ *
+ * A component gets its data from `useWidget(widget)`, typed straight off the
+ * widget's own `data` schema. There is no generated helpers file and no server
+ * type import, so a widget cannot drift from its contract.
+ */
+
+import { useToolInfo } from "skybridge/web";
+import type { Infer, Shape, WidgetDefinition } from "./index.js";
+
+export {
+	mountView,
+	useCallTool,
+	useDisplayMode,
+	useDownload,
+	useFiles,
+	useLayout,
+	useOpenExternal,
+	useRequestClose,
+	useRequestModal,
+	useRequestSize,
+	useSendFollowUpMessage,
+	useSetOpenInAppUrl,
+	useUser,
+} from "skybridge/web";
+
+/**
+ * Per-widget state that survives re-renders and is handed back to the host.
+ *
+ * Upstream this is `useViewState`. The name here follows the wire format
+ * instead: what reaches ChatGPT is `openai/widgetCSP`, `openai/widgetDescription`,
+ * and `window.openai.widgetState`. Holding the public vocabulary steady is also
+ * the point of the package — the upstream rename of widgets to views cost app
+ * repos nothing, and it should keep costing them nothing.
+ */
+export { useViewState as useWidgetState } from "skybridge/web";
+
+export { defineWidget } from "./index.js";
+export type { Infer, Shape, WidgetDefinition } from "./index.js";
+
+export type UseWidgetResult<S extends Shape> = {
+	/**
+	 * The widget's data. Present as soon as the host has the tool input, which
+	 * on most hosts is before the server responds — so render optimistically.
+	 */
+	data: Infer<S> | undefined;
+	/** The host is still streaming the tool call. */
+	isLoading: boolean;
+	/** The server has responded and `data` is final. */
+	isReady: boolean;
+};
+
+/**
+ * Read this widget's data.
+ *
+ * @param _widget the widget contract, passed for type inference only
+ */
+export function useWidget<S extends Shape>(_widget: WidgetDefinition<S>): UseWidgetResult<S> {
+	const info = useToolInfo();
+	const data = (info.output ?? info.input) as Infer<S> | undefined;
+
+	return {
+		data,
+		isLoading: !info.isSuccess,
+		isReady: info.isSuccess,
+	};
+}