Hi

\"\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\" urls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.\nIf you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page\nor by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})` instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use: `

`\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified\n- **View Source:** Add a view source link by importing & using `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add `` to HTML to capture client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same version\n- **Styling:** Default to using TailwindCSS via `` unless otherwise specified\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n```\n├── backend/\n│ ├── database/\n│ │ ├── migrations.ts # Schema definitions\n│ │ ├── queries.ts # DB query functions\n│ │ └── README.md\n│ └── routes/ # Route modules\n│ ├── [route].ts\n│ └── static.ts # Static file serving\n│ ├── index.ts # Main entry point\n│ └── README.md\n├── frontend/\n│ ├── components/\n│ │ ├── App.tsx\n│ │ └── [Component].tsx\n│ ├── favicon.svg\n│ ├── index.html # Main HTML template\n│ ├── index.tsx # Frontend JS entry point\n│ ├── README.md\n│ └── style.css\n├── README.md\n└── shared/\n ├── README.md\n └── utils.ts # Shared types and functions\n```\n\n### Backend (Hono) Best Practices\n\n- Hono is the recommended API framework\n- Main entry point should be `backend/index.ts`\n- **Static asset serving:** Use the utility functions to read and serve project files:\n ```ts\n import { readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n \n // serve all files in frontend/ and shared/\n app.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\n app.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n \n // For index.html, often you'll want to bootstrap with initial data\n app.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n \n // Inject data to avoid extra round-trips\n const initialData = await fetchInitialData();\n const dataScript = ``;\n \n html = html.replace(\"\", `${dataScript}`);\n return c.html(html);\n });\n ```\n- Create RESTful API routes for CRUD operations\n- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:\n ```ts\n // Unwrap Hono errors to see original error details\n app.onError((err, c) => {\n throw err;\n });\n ```\n\n### Database Patterns\n- Run migrations on startup or comment out for performance\n- Change table names when modifying schemas rather than altering\n- Export clear query functions with proper TypeScript typing\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:** \n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`\n\n",[165],"4a3391d4-a5c0-11f0-a261-0224a6c84d84",".vtignore","0199cd92-ced6-71e8-a8db-d09800f4c479",["D",1760090574500],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[172],"4a3390da-a5c0-11f0-a261-0224a6c84d84","shared","0199cd92-ced6-71e8-a8db-cf40b0fa17d8",["D",1760090574500],"directory",[178],"4a338d60-a5c0-11f0-a261-0224a6c84d84","frontend","0199cd92-ced6-71e8-a8db-c34ad08bf163",["D",1760090574500],[184],"4a337f50-a5c0-11f0-a261-0224a6c84d84","backend","0199cd92-ced6-71e8-a8db-970fdcba0196",["D",1760090574500],[189],"pulls","branches","forks",5,"envVars",{"_201":153,"_203":153},"connections",{"_201":153,"_202":153},"count","unfilledCount","emptyCount",{"_42":188,"_32":189,"_30":190,"_150":-5,"_40":41,"_39":62,"_151":25,"_37":466,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":467,"_27":468},{"_42":462,"_32":434,"_30":429,"_150":190,"_40":41,"_39":62,"_151":25,"_37":463,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":464,"_27":465},{"_42":456,"_32":158,"_30":457,"_150":429,"_40":41,"_39":62,"_151":48,"_37":458,"_13":153,"_34":20,"_35":459,"_24":48,"_155":-5,"_240":460,"_27":461},{"_42":449,"_32":450,"_30":451,"_150":429,"_40":41,"_39":62,"_151":25,"_37":452,"_13":153,"_34":257,"_35":453,"_24":48,"_155":-5,"_240":454,"_27":455},{"_42":442,"_32":443,"_30":444,"_150":429,"_40":41,"_39":62,"_151":48,"_37":445,"_13":153,"_34":257,"_35":446,"_24":48,"_155":-5,"_240":447,"_27":448},{"_42":435,"_32":436,"_30":437,"_150":429,"_40":41,"_39":62,"_151":48,"_37":438,"_13":153,"_34":257,"_35":439,"_24":48,"_155":-5,"_240":440,"_27":441},{"_42":426,"_32":427,"_30":428,"_150":429,"_40":41,"_39":62,"_151":48,"_37":430,"_13":153,"_34":257,"_35":431,"_24":48,"_155":-5,"_240":432,"_27":433},{"_42":421,"_32":420,"_30":413,"_150":190,"_40":41,"_39":422,"_151":25,"_37":423,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":424,"_27":425},{"_42":410,"_32":411,"_30":412,"_150":413,"_40":41,"_39":414,"_151":48,"_37":415,"_13":416,"_34":257,"_35":417,"_24":48,"_155":-5,"_240":418,"_27":419},{"_42":404,"_32":158,"_30":405,"_150":190,"_40":41,"_39":62,"_151":48,"_37":406,"_13":153,"_34":20,"_35":407,"_24":48,"_155":-5,"_240":408,"_27":409},{"_42":395,"_32":396,"_30":57,"_150":190,"_40":41,"_39":397,"_151":48,"_37":398,"_13":399,"_34":400,"_35":401,"_24":48,"_155":-5,"_240":402,"_27":403},{"_42":183,"_32":184,"_30":185,"_150":-5,"_40":41,"_39":62,"_151":25,"_37":392,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":393,"_27":394},{"_42":388,"_32":353,"_30":383,"_150":185,"_40":41,"_39":62,"_151":48,"_37":389,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":390,"_27":391},{"_42":380,"_32":381,"_30":382,"_150":383,"_40":41,"_39":62,"_151":48,"_37":384,"_13":153,"_34":257,"_35":385,"_24":48,"_155":-5,"_240":386,"_27":387},{"_42":375,"_32":303,"_30":297,"_150":185,"_40":41,"_39":376,"_151":25,"_37":377,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":378,"_27":379},{"_42":370,"_32":353,"_30":347,"_150":297,"_40":41,"_39":371,"_151":25,"_37":372,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":373,"_27":374},{"_42":362,"_32":363,"_30":364,"_150":347,"_40":41,"_39":365,"_151":25,"_37":366,"_13":266,"_34":257,"_35":367,"_24":48,"_155":-5,"_240":368,"_27":369},{"_42":354,"_32":355,"_30":356,"_150":347,"_40":41,"_39":357,"_151":25,"_37":358,"_13":266,"_34":257,"_35":359,"_24":48,"_155":-5,"_240":360,"_27":361},{"_42":344,"_32":345,"_30":346,"_150":347,"_40":41,"_39":348,"_151":25,"_37":349,"_13":266,"_34":257,"_35":350,"_24":48,"_155":-5,"_240":351,"_27":352},{"_42":336,"_32":337,"_30":338,"_150":297,"_40":41,"_39":339,"_151":25,"_37":340,"_13":266,"_34":257,"_35":341,"_24":48,"_155":-5,"_240":342,"_27":343},{"_42":328,"_32":329,"_30":330,"_150":297,"_40":41,"_39":331,"_151":25,"_37":332,"_13":62,"_34":257,"_35":333,"_24":48,"_155":-5,"_240":334,"_27":335},{"_42":320,"_32":280,"_30":321,"_150":297,"_40":41,"_39":322,"_151":25,"_37":323,"_13":324,"_34":20,"_35":325,"_24":48,"_155":-5,"_240":326,"_27":327},{"_42":312,"_32":313,"_30":314,"_150":297,"_40":41,"_39":315,"_151":25,"_37":316,"_13":266,"_34":257,"_35":317,"_24":48,"_155":-5,"_240":318,"_27":319},{"_42":304,"_32":305,"_30":306,"_150":297,"_40":41,"_39":307,"_151":25,"_37":308,"_13":266,"_34":257,"_35":309,"_24":48,"_155":-5,"_240":310,"_27":311},{"_42":294,"_32":295,"_30":296,"_150":297,"_40":41,"_39":298,"_151":25,"_37":299,"_13":266,"_34":257,"_35":300,"_24":48,"_155":-5,"_240":301,"_27":302},{"_42":287,"_32":288,"_30":289,"_150":185,"_40":41,"_39":62,"_151":48,"_37":290,"_13":153,"_34":20,"_35":291,"_24":48,"_155":-5,"_240":292,"_27":293},{"_42":279,"_32":280,"_30":281,"_150":185,"_40":41,"_39":282,"_151":48,"_37":283,"_13":62,"_34":20,"_35":284,"_24":48,"_155":-5,"_240":285,"_27":286},{"_42":177,"_32":178,"_30":179,"_150":-5,"_40":41,"_39":62,"_151":25,"_37":276,"_13":153,"_34":181,"_35":-5,"_24":48,"_155":-5,"_240":277,"_27":278},{"_42":270,"_32":158,"_30":271,"_150":179,"_40":41,"_39":62,"_151":25,"_37":272,"_13":153,"_34":20,"_35":273,"_24":48,"_155":-5,"_240":274,"_27":275},{"_42":261,"_32":262,"_30":263,"_150":179,"_40":41,"_39":264,"_151":25,"_37":265,"_13":266,"_34":257,"_35":267,"_24":48,"_155":-5,"_240":268,"_27":269},{"_42":252,"_32":253,"_30":254,"_150":179,"_40":41,"_39":255,"_151":25,"_37":256,"_13":62,"_34":257,"_35":258,"_24":48,"_155":-5,"_240":259,"_27":260},{"_42":171,"_32":172,"_30":173,"_150":-5,"_40":41,"_39":62,"_151":25,"_37":249,"_13":153,"_34":20,"_35":175,"_24":48,"_155":-5,"_240":250,"_27":251},{"_42":164,"_32":165,"_30":166,"_150":-5,"_40":41,"_39":167,"_151":48,"_37":246,"_13":153,"_34":20,"_35":169,"_24":48,"_155":-5,"_240":247,"_27":248},{"_42":157,"_32":158,"_30":159,"_150":-5,"_40":41,"_39":160,"_151":48,"_37":243,"_13":62,"_34":20,"_35":162,"_24":48,"_155":-5,"_240":244,"_27":245},{"_42":147,"_32":148,"_30":149,"_150":-5,"_40":41,"_39":62,"_151":25,"_37":239,"_13":153,"_34":20,"_35":154,"_24":48,"_155":-5,"_240":241,"_27":242},["D",1760090574500],"children",[],[148],["D",1760093413636],[],[158],["D",1760093413426],[],[165],["D",1760090574500],[],[172],"2bc24bac-a5c8-11f0-9d67-0224a6c84d84","utils.ts","0199cd92-ced6-71e8-a8db-cb925ef7126e",37,["D",1760093959460],"script","export type { Message } from \"./types.ts\";\n\nexport const MESSAGE_LIMIT = 5;",[],[178,253],"617eaef6-a5d3-11f0-b0b7-0224a6c84d84","types.ts","e635c9ac-a5c6-11f0-957a-0224a6c84d84",60,["D",1760098774076],2,"import { z } from \"https://esm.sh/zod@4\";\n\n// Message schema\nexport const MessageSchema = z.object({\n id: z.number(),\n content: z.string(),\n timestamp: z.string(),\n});\n\n// Widget output schemas with discriminators\nexport const MessageListOutputSchema = z.object({\n kind: z.literal(\"message_list\"),\n messages: z.array(MessageSchema),\n});\n\nexport const MessageDetailOutputSchema = MessageSchema.extend({\n kind: z.literal(\"message_detail\"),\n});\n\n// Inferred TypeScript types\nexport type Message = z.infer;\nexport type MessageListOutput = z.infer;\nexport type MessageDetailOutput = z.infer;\n\n// Discriminated union for all widget states\nexport type WidgetState = MessageListOutput | MessageDetailOutput;\n",[],[178,262],"4a338e5a-a5c0-11f0-a261-0224a6c84d84","0199cd92-ced6-71e8-a8db-c55b5ac92619",["D",1760090574500],"# Shared\n\nIt's common to have code and types that are needed on both the frontend and the backend. It's important that you write this code in a particularly defensive way because it's limited by what both environments support:\n\n![shapes at 25-02-25 11.57.13.png](https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/75db1d51-d9b3-45e0-d178-25d886c10700/public)\n\nFor example, you *cannot* use the `Deno` keyword. For imports, you can't use `npm:` specifiers, so we reccomend `https://esm.sh` because it works on the server & client. You *can* use TypeScript because that is transpiled in `/backend/index.ts` for the frontend. Most code that works on the frontend tends to work in Deno, because Deno is designed to support \"web-standards\", but there are definitely edge cases to look out for.",[],[178,158],["D",1760090574500],[232,233,234],[178],"17f82eb6-a5d7-11f0-adc3-0224a6c84d84","index.html","0199cd92-ced6-71e8-a8db-b7f39d7bbf71",76,["D",1760100368693],"\n\n\n \n \n Val Town ChatGPT App SDK Starter\n \n\n\n

Val Town ChatGPT App SDK Starter

A starter template for building ChatGPT apps with MCP (Model Context Protocol) widgets on Val Town.

\n\n

Setup Instructions

\n Copy your MCP endpoint URL:\n
\n
\n Add to ChatGPT:\n
- Open ChatGPT settings
- Navigate to \"Apps\" or \"Integrations\"
- Click \"Add MCP Server\"
- Paste your MCP endpoint URL
\n
\n Test the integration:\n
- Ask ChatGPT: \"List all messages\"
- The widget should appear with the message board interface
\n

\n\n

Available Tools

list_messages - Shows all messages in a widget
get_message - Shows details for a specific message

\n\n

Development

Edit the code in backend/ and frontend/widgets/ to customize your app. Changes deploy instantly to Val Town.

\n\n \n\n\n",[],[184,280],"4a338888-a5c0-11f0-a261-0224a6c84d84","favicon.svg","0199cd92-ced6-71e8-a8db-b02e83e183ac",["D",1760090574500],"",[],[184,288],"39c53362-a5d3-11f0-970b-0224a6c84d84","widget.tsx","e5d97ba2-a5c6-11f0-9a0f-0224a6c84d84","394c4182-a5d3-11f0-967a-0224a6c84d84",52,["D",1760098707102],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { createRoot } from \"https://esm.sh/react-dom@19/client?deps=react@19\";\nimport { RouterProvider } from \"https://esm.sh/@tanstack/react-router@1?deps=react@19\";\nimport { router } from \"./routes.tsx\";\n\nconst appElement = document.getElementById(\"app\");\nif (!appElement) {\n throw new Error(\"App element not found\");\n}\n\nconst root = createRoot(appElement);\nroot.render();\n",[],[184,303,295],"widgets","39ba6fb8-a5d3-11f0-a38e-0224a6c84d84","routes.tsx","e61b5824-a5c6-11f0-8fd8-0224a6c84d84",51,["D",1760098707358],"/** @jsxImportSource https://esm.sh/react@19 */\nimport {\n createRootRoute,\n createRoute,\n createRouter,\n Outlet,\n} from \"https://esm.sh/@tanstack/react-router@1?deps=react@19\";\nimport { LoadingWidget } from \"./components/LoadingWidget.tsx\";\nimport { MessageListWidget } from \"./components/MessageListWidget.tsx\";\nimport { MessageDetailWidget } from \"./components/MessageDetailWidget.tsx\";\nimport { NavigationSync } from \"./NavigationSync.tsx\";\n\nfunction RootComponent() {\n return (\n <>\n \n \n \n );\n}\n\nconst rootRoute = createRootRoute({\n component: RootComponent,\n});\n\nconst loadingRoute = createRoute({\n getParentRoute: () => rootRoute,\n path: \"/\",\n component: LoadingWidget,\n});\n\nconst listRoute = createRoute({\n getParentRoute: () => rootRoute,\n path: \"/list\",\n component: MessageListWidget,\n});\n\nconst detailRoute = createRoute({\n getParentRoute: () => rootRoute,\n path: \"/detail/$messageId\",\n component: MessageDetailWidget,\n});\n\nconst routeTree = rootRoute.addChildren([\n loadingRoute,\n listRoute,\n detailRoute,\n]);\n\nexport const router = createRouter({ routeTree });\n\ndeclare module \"https://esm.sh/@tanstack/react-router@1?deps=react@19\" {\n interface Register {\n router: typeof router;\n }\n}\n",[],[184,303,305],"39dd663a-a5d3-11f0-b75f-0224a6c84d84","openai-types.ts","e6a3256a-a5c6-11f0-bf4c-0224a6c84d84",55,["D",1760098707587],"type UnknownObject = Record;\n\nexport interface OpenAiGlobals<\n ToolInput extends UnknownObject = UnknownObject,\n ToolOutput extends UnknownObject = UnknownObject,\n ToolResponseMetadata extends UnknownObject = UnknownObject,\n WidgetState extends UnknownObject = UnknownObject,\n> {\n theme: \"light\" | \"dark\";\n userAgent: {\n device: { type: \"mobile\" | \"tablet\" | \"desktop\" | \"unknown\" };\n capabilities: {\n hover: boolean;\n touch: boolean;\n };\n };\n locale: string;\n maxHeight: number;\n displayMode: \"pip\" | \"inline\" | \"fullscreen\";\n safeArea: {\n insets: {\n top: number;\n bottom: number;\n left: number;\n right: number;\n };\n };\n toolInput: ToolInput;\n toolOutput: ToolOutput | null;\n toolResponseMetadata: ToolResponseMetadata | null;\n widgetState: WidgetState | null;\n}\n\nexport interface OpenAIWidgetAPI<\n ToolInput extends UnknownObject = UnknownObject,\n ToolOutput extends UnknownObject = UnknownObject,\n ToolResponseMetadata extends UnknownObject = UnknownObject,\n WidgetState extends UnknownObject = UnknownObject,\n> extends OpenAiGlobals<\n ToolInput,\n ToolOutput,\n ToolResponseMetadata,\n WidgetState\n > {\n setWidgetState: (state: WidgetState) => Promise;\n callTool: (name: string, args: unknown) => Promise;\n sendFollowUpMessage: (params: { prompt: string }) => Promise;\n requestDisplayMode: (mode: \"pip\" | \"inline\" | \"fullscreen\") => Promise;\n}\n\nexport const SET_GLOBALS_EVENT_TYPE = \"openai:set_globals\";\n\nexport interface SetGlobalsEvent\n extends CustomEvent<{ globals: Partial }> {\n type: typeof SET_GLOBALS_EVENT_TYPE;\n}\n\ndeclare global {\n interface Window {\n openai: OpenAIWidgetAPI;\n }\n\n interface WindowEventMap {\n [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;\n }\n}\n\nexport function getOpenAI(): OpenAIWidgetAPI | undefined {\n return window.openai;\n}\n",[],[184,303,313],"182d3b1a-a5d7-11f0-927d-0224a6c84d84","45792f88-a5d3-11f0-80bc-0224a6c84d84",82,["D",1760100368717],3,"\n\n \n \n \n Widget\n \n \n \n \n

\n \n \n\n",[],[184,303,280],"3990cfe6-a5d3-11f0-9f65-0224a6c84d84","hooks.ts","2ba96e48-a5c8-11f0-85d6-0224a6c84d84",47,["D",1760098707085],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { useCallback, useEffect, useState, useSyncExternalStore } from \"https://esm.sh/react@19\";\nimport type { OpenAiGlobals, SetGlobalsEvent } from \"./openai-types.ts\";\nimport { getOpenAI, SET_GLOBALS_EVENT_TYPE } from \"./openai-types.ts\";\n\ntype UnknownObject = Record;\n\nexport function useOpenAiGlobal(\n key: K,\n): OpenAiGlobals[K] {\n return useSyncExternalStore(\n (onChange) => {\n function handleSetGlobal(event: Event) {\n const setGlobalsEvent = event as SetGlobalsEvent;\n const value = setGlobalsEvent.detail?.globals[key];\n\n if (value === undefined) return;\n onChange();\n }\n\n window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {\n passive: true,\n });\n\n return () => {\n window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);\n };\n },\n () => window.openai[key],\n );\n}\n\nexport function useToolOutput(): T | null {\n return useOpenAiGlobal(\"toolOutput\") as T | null;\n}\n\nexport function useTheme(): \"light\" | \"dark\" {\n return useOpenAiGlobal(\"theme\");\n}\n\nexport function useWidgetState(\n defaultState: T | (() => T),\n): readonly [T, (state: React.SetStateAction) => void] {\n const widgetStateFromWindow = useOpenAiGlobal(\"widgetState\") as T | null;\n\n const [widgetState, _setWidgetState] = useState(() => {\n return (\n widgetStateFromWindow ??\n (typeof defaultState === \"function\" ? defaultState() : defaultState)\n );\n });\n\n useEffect(() => {\n if (widgetStateFromWindow) {\n _setWidgetState(widgetStateFromWindow);\n }\n }, [widgetStateFromWindow]);\n\n const setWidgetState = useCallback(\n (stateOrUpdater: React.SetStateAction) => {\n _setWidgetState((prevState) => {\n const newState =\n typeof stateOrUpdater === \"function\"\n ? (stateOrUpdater as (prev: T) => T)(prevState)\n : stateOrUpdater;\n\n getOpenAI()?.setWidgetState(newState);\n return newState;\n });\n },\n [],\n );\n\n return [widgetState, setWidgetState] as const;\n}\n",[],[184,303,329],"39c9e5ec-a5d3-11f0-a38e-0224a6c84d84","NavigationSync.tsx","e5e8a2d0-a5c6-11f0-89f6-0224a6c84d84",53,["D",1760098707426],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { useEffect } from \"https://esm.sh/react@19\";\nimport { useNavigate } from \"https://esm.sh/@tanstack/react-router@1?deps=react@19\";\nimport { useToolOutput } from \"./hooks.ts\";\nimport type { WidgetState } from \"../../shared/types.ts\";\n\nexport function NavigationSync() {\n const data = useToolOutput();\n const navigate = useNavigate();\n\n useEffect(() => {\n if (!data) {\n navigate({ to: \"/\" });\n return;\n }\n\n switch (data.kind) {\n case \"message_list\":\n navigate({ to: \"/list\" });\n break;\n\n case \"message_detail\":\n navigate({\n to: \"/detail/$messageId\",\n params: { messageId: String(data.id) },\n });\n break;\n }\n }, [data, navigate]);\n\n return null;\n}\n",[],[184,303,337],"099926f0-a5d6-11f0-a7b5-0224a6c84d84","MessageListWidget.tsx","2ba23c54-a5c8-11f0-85d6-0224a6c84d84","396a41aa-a5d3-11f0-9f65-0224a6c84d84",75,["D",1760099915065],"/** @jsxImportSource https://esm.sh/react@19 */\nimport type { MessageListOutput } from \"../../../shared/types.ts\";\nimport { useTheme, useToolOutput } from \"../hooks.ts\";\nimport { getOpenAI } from \"../openai-types.ts\";\n\nexport function MessageListWidget() {\n const data = useToolOutput();\n const theme = useTheme();\n const isDark = theme === \"dark\";\n\n if (!data || data.kind !== \"message_list\") {\n return (\n \n

\n \n \n Loading messages...\n

\n \n );\n }\n\n const { messages } = data;\n\n async function handleAddMessage() {\n await getOpenAI()?.sendFollowUpMessage({\n prompt: \"Add a new message\",\n });\n }\n\n return (\n \n

Messages

\n \n + Add Message\n \n

\n\n {messages.length === 0 ? (\n \n

No messages yet

Click \"Add Message\" to create one

\n \n ) : (\n

\n {messages.map((message) => (\n \n ))}\n

\n )}\n \n );\n}\n\nfunction MessageCard({ message, isDark }) {\n return (\n \n

{message.content}

\n \n {new Date(message.timestamp).toLocaleString()}\n \n \n #{message.id}\n \n

\n \n );\n}\n",[],[184,303,353,345],"components","0993a572-a5d6-11f0-9fc2-0224a6c84d84","MessageDetailWidget.tsx","2b98a41e-a5c8-11f0-afda-0224a6c84d84",74,["D",1760099915027],"/** @jsxImportSource https://esm.sh/react@19 */\nimport type { MessageDetailOutput } from \"../../../shared/types.ts\";\nimport { useTheme, useToolOutput } from \"../hooks.ts\";\nimport { getOpenAI } from \"../openai-types.ts\";\n\nexport function MessageDetailWidget() {\n const data = useToolOutput();\n const theme = useTheme();\n const isDark = theme === \"dark\";\n\n async function handleBackToList() {\n await getOpenAI()?.sendFollowUpMessage({\n prompt: \"Show me all messages\",\n });\n }\n\n if (!data || data.kind !== \"message_detail\") {\n return (\n \n

\n \n \n Loading message...\n

\n \n );\n }\n\n return (\n \n

Message Details

\n\n \n

{data.content}

\n \n\n

\n \n ID\n

{data.id}

\n\n

\n \n CREATED\n

\n {new Date(data.timestamp).toLocaleString()}\n

\n \n \n\n \n ← Back to List\n \n \n );\n}\n",[],[184,303,353,355],"098e318c-a5d6-11f0-9400-0224a6c84d84","LoadingWidget.tsx","2b8dee70-a5c8-11f0-aace-0224a6c84d84",73,["D",1760099915027],"/** @jsxImportSource https://esm.sh/react@19 */\nimport { useTheme } from \"../hooks.ts\";\n\nexport function LoadingWidget() {\n const theme = useTheme();\n const isDark = theme === \"dark\";\n\n return (\n \n

\n \n \n Loading...\n

\n \n );\n}\n",[],[184,303,353,363],"396a40e2-a5d3-11f0-9f65-0224a6c84d84",46,["D",1760098706836],[220,221,222],[184,303,353],"394c40a6-a5d3-11f0-967a-0224a6c84d84",45,["D",1760098706637],[219,223,224,225,226,227,228],[184,303],"4a33807c-a5c0-11f0-a261-0224a6c84d84","App.tsx","0199cd92-ced6-71e8-a8db-982d78191cab","0199cd92-ced6-71e8-a8db-a030bc256dc9",["D",1760090574500],"/** @jsxImportSource https://esm.sh/react@19 */\nimport React from \"https://esm.sh/react@19\";\nimport { type Message, MESSAGE_LIMIT } from \"../../shared/utils.ts\";\nimport { MessageInput } from \"./MessageInput.tsx\";\nimport { useMessages } from \"../lib/queries.ts\";\n\nexport function App(\n { initialMessages = [], thisProjectURL }: { initialMessages?: Message[]; thisProjectURL?: string },\n) {\n const { data: messages = [], isLoading, error } = useMessages(initialMessages);\n\n if (isLoading && !initialMessages.length) {\n return (\n

Loading messages...

\n );\n }\n\n if (error) {\n return (\n

Failed to load messages

\n );\n }\n\n return (\n

💬 Message Board!

\n \n \n {thisProjectURL\n ? (\n \n )\n : null}\n

\n );\n}\n\nfunction MessageList({ messages }: { messages: Message[] }) {\n const displayedMessages = messages.slice(0, MESSAGE_LIMIT);\n return (\n

\n {displayedMessages.map((msg) => )}\n

\n );\n}\n\nfunction MessageItem({ message }) {\n const formattedDate = new Date(message.timestamp).toLocaleString();\n\n return (\n

{message.content}

\n {formattedDate}\n

\n );\n}",[],[184,353,381],"4a33843c-a5c0-11f0-a261-0224a6c84d84",["D",1760090574500],[217],[184,353],["D",1760090574500],[216,218,229,230],[184],"17fe5b60-a5d7-11f0-9d94-0224a6c84d84","index.ts",77,["D",1760100368702],9,"http","import { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { Hono } from \"npm:hono\";\nimport { cors } from \"npm:hono/cors\";\nimport { mcpHandler, setBaseUrl } from \"./mcp/server.ts\";\n\nconst app = new Hono();\n\n// Enable CORS for widget assets (ChatGPT iframe needs this)\napp.use(\"/widget-assets/*\", cors({\n origin: \"*\",\n allowMethods: [\"GET\", \"HEAD\", \"OPTIONS\"],\n}));\n\n// Serve setup instructions at the root /\napp.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n\n // Get this project's URL, in a way that works across forks and branches\n const projectVal = parseProject(import.meta.url);\n const thisProjectURL = projectVal.links.self.project;\n\n // Inject the project URL for the setup instructions\n const dataScript = ``;\n\n // Insert the script right before the closing tag\n html = html.replace(\"\", `${dataScript}`);\n\n return c.html(html);\n});\n\n// MCP endpoint for ChatGPT\napp.all(\"/mcp\", async (c) => {\n // Set base URL before handling MCP request\n const url = new URL(c.req.url);\n setBaseUrl(`${url.protocol}//${url.host}`);\n\n const response = await mcpHandler(c.req.raw);\n return response;\n});\n\n// Serve widget assets with automatic transpilation\napp.get(\"/widget-assets/**/*\", (c) => {\n return serveFile(c.req.path.replace(\"/widget-assets\", \"/frontend/widgets\"), import.meta.url);\n});\n\n// Unwrap and rethrow Hono errors as the original error\n// If you delete this, all errors will be \"Internal Server Error\"\napp.onError((err, c) => {\n throw err;\n});\n\n// HTTP vals expect an exported \"fetch handler\"\n// This is how you \"run the server\" in Val Town with Hono\nexport default app.fetch;",[],[189,396],"4a337668-a5c0-11f0-a261-0224a6c84d84","0199cd92-ced6-71e8-a8db-8f648d1afba4",["D",1760090574500],"# Backend\n\nThis folder contains all backend-only code in this project. It's broken up into:\n\n* `index.ts` - this is the **entrypoint** for this whole project\n* `database/` - this contains the code for interfacing with the app's SQLite database table\n\n## Hono\n\nThis app uses [Hono](https://hono.dev/) as the API framework. You can think of Hono as a replacement for [ExpressJS](https://expressjs.com/) that works in serverless environments like Val Town or Cloudflare Workers. If you come from Python or Ruby, Hono is also a lot like [Flask](https://github.com/pallets/flask) or [Sinatra](https://github.com/sinatra/sinatra), respectively.\n\n## Serving assets to the frontend\n\nThis backend HTTP server is responsible for serving all static assets to the browser to render the app, including HTML, JavaScript (including all client-side React), CSS, and even the favicon SVG.\n\nIn a normal server environment, you would likely use a middleware [like this one](https://hono.dev/docs/getting-started/nodejs#serve-static-files) to serve static files. Some frameworks or deployment platforms automatically make any content inside a `public/` folder public. \n\nHowever in Val Town you need to handle this yourself, and it can be suprisingly difficult to read and serve files in a Val Town Project. This template uses helper functions from [stevekrouse/utils/serve-public](https://www.val.town/x/stevekrouse/utils/branch/main/code/serve-public/README.md), which handle reading project files in a way that will work across branches and forks, automatically transpiles typescript to javascript, and assigns content-types based on the file's extension.\n\n### `index.html`\n\nThe most complicated part of this backend API is serving index.html. In this app (like most apps) we serve it at the root, ie `GET /`. \n\nWe *bootstrap* `index.html` with some initial data from the server, so that it gets dynamically injected JSON data without having to make another round-trip request to the server to get that data on the frontend. This is a common pattern for client-side rendered apps.\n\n## CRUD API Routes\n\nThis app has two CRUD API routes: for reading and inserting into the messages table. They both speak JSON, which is standard. They import their functions from `/backend/database/queries.ts`. These routes are called from the React app to refresh and update data.\n\n## Errors\n\nHono and other API frameworks have a habit of swallowing up Errors. We turn off this default behavior by re-throwing errors, because we think most of the time you'll want to see the full stack trace instead of merely \"Internal Server Error\". You can customize how you want errors to appear.",[],[189,158],"a765a878-a5d5-11f0-b659-0224a6c84d84","server.ts","e639b350-a5c6-11f0-b39d-0224a6c84d84","e5bb5ac8-a5c6-11f0-9a0f-0224a6c84d84",71,["D",1760099750343],7,"import { McpServer, StreamableHttpTransport } from \"https://esm.sh/mcp-lite@0.8.1\";\nimport { readFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { z } from \"https://esm.sh/zod@4\";\nimport { getMessages } from \"../database/queries.ts\";\nimport {\n MessageListOutputSchema,\n MessageDetailOutputSchema,\n} from \"../../shared/types.ts\";\n\nconst WIDGET_URI = \"ui://widget/index.html\";\n\n// Store current base URL (set per request)\nlet currentBaseUrl = \"\";\n\nexport function setBaseUrl(url: string) {\n currentBaseUrl = url;\n}\n\nfunction getBaseUrl(): string {\n if (!currentBaseUrl) {\n throw new Error(\"Base URL not set - must call setBaseUrl before handling MCP requests\");\n }\n return currentBaseUrl;\n}\n\nfunction widgetMeta(invoking?: string, invoked?: string) {\n return {\n \"openai/outputTemplate\": WIDGET_URI,\n \"openai/toolInvocation/invoking\": invoking,\n \"openai/toolInvocation/invoked\": invoked,\n \"openai/widgetAccessible\": true,\n \"openai/resultCanProduceWidget\": true,\n } as const;\n}\n\nconst mcp = new McpServer({\n name: \"valtown-message-board\",\n version: \"1.0.0\",\n schemaAdapter: (schema) => z.toJSONSchema(schema as z.ZodType),\n});\n\nasync function loadWidgetHtml(baseUrl: string): Promise {\n let html = await readFile(\"/frontend/widgets/index.html\", import.meta.url);\n html = html.replaceAll(\"__VAL_TOWN_URL__\", baseUrl);\n return html;\n}\n\nmcp.resource(\n WIDGET_URI,\n {\n name: \"Message Board Widget\",\n description: \"Interactive message board widget\",\n mimeType: \"text/html+skybridge\",\n },\n async (uri) => {\n const baseUrl = getBaseUrl();\n const html = await loadWidgetHtml(baseUrl);\n\n return {\n contents: [\n {\n uri: uri.href,\n type: \"text\",\n text: html,\n mimeType: \"text/html+skybridge\",\n _meta: {\n ...widgetMeta(),\n \"openai/widgetCSP\": {\n connect_domains: [baseUrl, \"https://esm.sh\", \"https://cdn.jsdelivr.net\"],\n resource_domains: [baseUrl, \"https://esm.sh\", \"https://cdn.jsdelivr.net\"],\n },\n },\n },\n ],\n };\n },\n);\n\nmcp.tool(\"list_messages\", {\n description: \"List all messages from the message board\",\n inputSchema: z.object({}),\n outputSchema: MessageListOutputSchema,\n _meta: widgetMeta(\"Loading messages...\", \"Messages loaded\"),\n handler: async () => {\n const messages = await getMessages();\n\n return {\n structuredContent: {\n kind: \"message_list\",\n messages,\n },\n content: [\n {\n type: \"text\",\n text: `Found ${messages.length} message${messages.length === 1 ? \"\" : \"s\"}`,\n },\n ],\n _meta: widgetMeta(),\n };\n },\n});\n\nmcp.tool(\"get_message\", {\n description: \"Get a specific message by ID\",\n inputSchema: z.object({\n id: z.number().describe(\"Message ID\"),\n }),\n outputSchema: MessageDetailOutputSchema,\n _meta: widgetMeta(\"Loading message...\", \"Message loaded\"),\n handler: async ({ id }) => {\n const messages = await getMessages();\n const message = messages.find((m) => m.id === id);\n\n if (!message) {\n throw new Error(`Message with ID ${id} not found`);\n }\n\n return {\n structuredContent: {\n kind: \"message_detail\",\n ...message,\n },\n content: [\n {\n type: \"text\",\n text: `Message #${id}: ${message.content}`,\n },\n ],\n _meta: widgetMeta(),\n };\n },\n});\n\nconst transport = new StreamableHttpTransport();\nexport const mcpHandler = transport.bind(mcp);\n",[],[189,420,411],"mcp","e5bb5a1e-a5c6-11f0-9a0f-0224a6c84d84",4,["D",1760093412477],[212],[189,420],"4a337316-a5c0-11f0-a261-0224a6c84d84","schema.ts","0199cd92-ced6-71e8-a8db-850ab1185000","0199cd92-ced6-71e8-a8db-8890d3b47b22",["D",1760090574500],"import { sqliteTable, text, integer } from \"npm:drizzle-orm/sqlite-core\";\n\n// Messages table\nexport const messages = sqliteTable(\"messages\", {\n id: integer(\"id\").primaryKey({ autoIncrement: true }),\n content: text(\"content\").notNull(),\n timestamp: text(\"timestamp\").notNull().default(new Date().toISOString()),\n});\n\n// Type exports\nexport type Message = typeof messages.$inferSelect;",[],[189,434,427],"database","4a3361aa-a5c0-11f0-a261-0224a6c84d84","queries.ts","0199cd92-ced6-71e8-a8db-822272cd45fd",["D",1760090574500],"import { desc } from \"npm:drizzle-orm\";\nimport { db, schema } from \"./db.ts\";\nimport { createTables } from \"./migrations.ts\";\nimport { MESSAGE_LIMIT } from \"../../shared/utils.ts\";\n\n// This will create the database table if it doesn't exist.\n// This will run every time the app starts up. You can\n// comment out this line for a modest (30ms) performance improvement\n// on cold starts. It's left in to ensure the database tables are\n// automatically set up correctly for users who fork this app.\nawait createTables();\n\nexport async function getMessages(limit = MESSAGE_LIMIT) {\n const messages = await db\n .select()\n .from(schema.messages)\n .orderBy(desc(schema.messages.timestamp))\n .limit(limit)\n .all();\n \n return messages;\n}\n\nexport async function insertMessage(content: string) {\n await db\n .insert(schema.messages)\n .values({\n content,\n timestamp: new Date().toISOString(),\n })\n .run();\n}",[],[189,434,436],"4a336060-a5c0-11f0-a261-0224a6c84d84","migrations.ts","0199cd92-ced6-71e8-a8db-7d5d2a4bb2ae",["D",1760090574500],"import { sql } from \"npm:drizzle-orm\";\nimport { db } from \"./db.ts\";\n\nexport async function createTables() {\n // Uncomment to reset database\n await db.run(sql`DROP TABLE IF EXISTS messages`);\n // Create messages table\n await db.run(sql`\n CREATE TABLE IF NOT EXISTS messages (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n content TEXT NOT NULL,\n timestamp TEXT NOT NULL DEFAULT (datetime('now'))\n )\n `);\n}",[],[189,434,443],"4a335e6c-a5c0-11f0-a261-0224a6c84d84","db.ts","0199cd92-ced6-71e8-a8db-797489caa3cc",["D",1760090574500],"import { sqlite } from \"https://esm.town/v/std/sqlite\";\nimport { drizzle } from \"npm:drizzle-orm/libsql\";\nimport * as schema from \"./schema.ts\";\n\n// Create Drizzle instance with Val Town's sqlite\nexport const db = drizzle(sqlite as any);\n\n// Export schema for convenience\nexport { schema };",[],[189,434,450],"4a335430-a5c0-11f0-a261-0224a6c84d84","0199cd92-ced6-71e8-a8db-76bef76c0624",["D",1760090574500],"# Database\n\nThis app uses [Val Town SQLite](https://docs.val.town/std/sqlite/) to manage data. Every Val Town account comes with a free SQLite database, hosted on [Turso](https://turso.tech/). This folder is broken up into two files:\n\n* `migrations.ts` - code to set up the database tables the app needs\n* `queries.ts` - functions to run queries against those tables, which are imported and used in the main Hono server in `/backend/index.ts`\n\n## Migrations\n\nIn `backend/database/migrations.ts`, this app creates a new SQLite table `reactHonoStarter_messages` to store messages. \n\nThis \"migration\" runs once on every app startup because it's imported in `index.ts`. You can comment this line out for a slight (30ms) performance improvement on cold starts. It's left in so that users who fork this project will have the migration run correctly.\n\nSQLite has much more limited support for altering existing tables as compared to other databases. Often it's easier to create new tables with the schema you want, and then copy the data over. Happily LLMs are quite good at those sort of database operations, but please reach out in the [Val Town Discord](https://discord.com/invite/dHv45uN5RY) if you need help.\n\n## Queries\n\nThe queries file is where running the migrations happen in this app. It'd also be reasonable for that to happen in index.ts, or as is said above, for that line to be commented out, and only run when actual changes are made to your database schema.\n\nThe queries file exports functions to get and write data. It relies on shared types and data imported from the `/shared` directory.",[],[189,434,158],"4a337546-a5c0-11f0-a261-0224a6c84d84",["D",1760090574500],[206,207,208,209,210],[189,434],["D",1760090574500],[205,211,213,214],[189],["D",1760090574500],{"_99":98,"_106":102},{"_99":98,"_100":-5,"_101":102,"_18":55,"_103":104,"_105":48},{"_13":85,"_32":86,"_42":41,"_87":43,"_88":89,"_90":91,"_92":50,"_93":94,"_95":64,"_96":44,"_97":98},"ctx",{"_78":-5,"_128":506,"_507":508,"_509":510,"_511":48,"_512":48,"_513":48,"_514":25,"_515":-5,"_516":-7,"_517":-7,"_518":153,"_519":48,"_520":48,"_521":-5,"_522":48,"_523":48,"_524":48,"_525":-5},"ENV",{"_477":478,"_479":480,"_481":86,"_482":483,"_484":485,"_486":487,"_488":489,"_490":491,"_492":493,"_494":495,"_496":497,"_498":499,"_500":501,"_502":503,"_504":505},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v85