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 {\n parseProject,\n readFile,\n serveFile,\n} from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\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\"\nurls:\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\nStandard Library utilities ONLY RUN ON THE SERVER. If you need access to this\ndata on the client, run it in the server and pass it to the client by splicing\nit into the HTML page or by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use\n `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})`\n instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode\n symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use:\n `

`\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)\n unless otherwise specified\n- **View Source:** Add a view source link by importing & using\n `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the\n client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add\n `` to HTML to capture\n client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local\n resolution; Avoid catches that merely log or return 500s. Let errors bubble up\n with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but\n generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure\n compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer\n simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with\n `?deps=react@18.2.0,react-dom@18.2.0` and start the file with\n `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same\n version\n- **Styling:** Default to using TailwindCSS via\n `` unless otherwise\n specified\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n\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\n files:\n ```ts\n import {\n readFile,\n serveFile,\n } 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\n 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\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\n 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\n `export default app.fetch // This is the entry point for HTTP vals`",[168],"cac32640-c3dc-11f0-9928-42dde27851f2",".vtignore","cac3271c-c3dc-11f0-9928-42dde27851f2",4,["D",1763401351042],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor",[175],"cc47c946-c3e4-11f0-8a14-42dde27851f2","shared","cc47c9fa-c3e4-11f0-8a14-42dde27851f2",11,["D",1763404789566],"directory",[182],"cc29d652-c3e4-11f0-8a14-42dde27851f2","frontend","cc29d738-c3e4-11f0-8a14-42dde27851f2",9,["D",1763404789368],[189],"cc382342-c3e4-11f0-8a14-42dde27851f2","backend","cc382428-c3e4-11f0-8a14-42dde27851f2",10,["D",1763404789463],[195],"pulls","branches","forks","envVars",{"_207":141,"_209":62},"connections",{"_207":62,"_208":62},"count","unfilledCount","emptyCount",{"_43":194,"_32":195,"_30":196,"_137":-5,"_41":42,"_40":197,"_139":58,"_38":480,"_13":62,"_34":186,"_36":-5,"_23":24,"_143":-5,"_247":481,"_26":482},{"_43":475,"_32":466,"_30":460,"_137":196,"_41":42,"_40":476,"_139":58,"_38":477,"_13":62,"_34":186,"_36":-5,"_23":24,"_143":-5,"_247":478,"_26":479},{"_43":467,"_32":468,"_30":469,"_137":460,"_41":42,"_40":470,"_139":24,"_38":471,"_13":62,"_34":35,"_36":472,"_23":24,"_143":-5,"_247":473,"_26":474},{"_43":457,"_32":458,"_30":459,"_137":460,"_41":42,"_40":461,"_139":24,"_38":462,"_13":62,"_34":35,"_36":463,"_23":24,"_143":-5,"_247":464,"_26":465},{"_43":453,"_32":428,"_30":421,"_137":196,"_41":42,"_40":424,"_139":58,"_38":454,"_13":62,"_34":186,"_36":-5,"_23":24,"_143":-5,"_247":455,"_26":456},{"_43":445,"_32":446,"_30":447,"_137":421,"_41":42,"_40":448,"_139":24,"_38":449,"_13":62,"_34":35,"_36":450,"_23":24,"_143":-5,"_247":451,"_26":452},{"_43":437,"_32":438,"_30":439,"_137":421,"_41":42,"_40":440,"_139":24,"_38":441,"_13":62,"_34":35,"_36":442,"_23":24,"_143":-5,"_247":443,"_26":444},{"_43":429,"_32":430,"_30":431,"_137":421,"_41":42,"_40":432,"_139":24,"_38":433,"_13":62,"_34":35,"_36":434,"_23":24,"_143":-5,"_247":435,"_26":436},{"_43":418,"_32":419,"_30":420,"_137":421,"_41":42,"_40":422,"_139":24,"_38":423,"_13":424,"_34":35,"_36":425,"_23":24,"_143":-5,"_247":426,"_26":427},{"_43":410,"_32":411,"_30":56,"_137":196,"_41":42,"_40":412,"_139":24,"_38":413,"_13":62,"_34":414,"_36":415,"_23":24,"_143":45,"_247":416,"_26":417},{"_43":406,"_32":33,"_30":31,"_137":196,"_41":42,"_40":14,"_139":24,"_38":407,"_13":62,"_34":35,"_36":37,"_23":24,"_143":-5,"_247":408,"_26":409},{"_43":188,"_32":189,"_30":190,"_137":-5,"_41":42,"_40":191,"_139":58,"_38":403,"_13":62,"_34":186,"_36":-5,"_23":24,"_143":-5,"_247":404,"_26":405},{"_43":398,"_32":301,"_30":295,"_137":190,"_41":42,"_40":399,"_139":58,"_38":400,"_13":62,"_34":186,"_36":-5,"_23":24,"_143":-5,"_247":401,"_26":402},{"_43":390,"_32":391,"_30":392,"_137":295,"_41":42,"_40":393,"_139":24,"_38":394,"_13":141,"_34":35,"_36":395,"_23":24,"_143":-5,"_247":396,"_26":397},{"_43":382,"_32":383,"_30":384,"_137":295,"_41":42,"_40":385,"_139":24,"_38":386,"_13":62,"_34":35,"_36":387,"_23":24,"_143":-5,"_247":388,"_26":389},{"_43":374,"_32":375,"_30":376,"_137":295,"_41":42,"_40":377,"_139":24,"_38":378,"_13":62,"_34":35,"_36":379,"_23":24,"_143":-5,"_247":380,"_26":381},{"_43":366,"_32":367,"_30":368,"_137":295,"_41":42,"_40":369,"_139":24,"_38":370,"_13":62,"_34":35,"_36":371,"_23":24,"_143":-5,"_247":372,"_26":373},{"_43":358,"_32":359,"_30":360,"_137":295,"_41":42,"_40":361,"_139":24,"_38":362,"_13":62,"_34":35,"_36":363,"_23":24,"_143":-5,"_247":364,"_26":365},{"_43":350,"_32":351,"_30":352,"_137":295,"_41":42,"_40":353,"_139":24,"_38":354,"_13":62,"_34":35,"_36":355,"_23":24,"_143":-5,"_247":356,"_26":357},{"_43":342,"_32":343,"_30":344,"_137":295,"_41":42,"_40":345,"_139":24,"_38":346,"_13":62,"_34":35,"_36":347,"_23":24,"_143":-5,"_247":348,"_26":349},{"_43":334,"_32":335,"_30":336,"_137":295,"_41":42,"_40":337,"_139":24,"_38":338,"_13":62,"_34":35,"_36":339,"_23":24,"_143":-5,"_247":340,"_26":341},{"_43":326,"_32":327,"_30":328,"_137":295,"_41":42,"_40":329,"_139":24,"_38":330,"_13":62,"_34":35,"_36":331,"_23":24,"_143":-5,"_247":332,"_26":333},{"_43":318,"_32":319,"_30":320,"_137":295,"_41":42,"_40":321,"_139":24,"_38":322,"_13":62,"_34":35,"_36":323,"_23":24,"_143":-5,"_247":324,"_26":325},{"_43":310,"_32":311,"_30":312,"_137":295,"_41":42,"_40":313,"_139":24,"_38":314,"_13":62,"_34":35,"_36":315,"_23":24,"_143":-5,"_247":316,"_26":317},{"_43":302,"_32":303,"_30":304,"_137":295,"_41":42,"_40":305,"_139":24,"_38":306,"_13":62,"_34":35,"_36":307,"_23":24,"_143":-5,"_247":308,"_26":309},{"_43":292,"_32":293,"_30":294,"_137":295,"_41":42,"_40":296,"_139":24,"_38":297,"_13":62,"_34":35,"_36":298,"_23":24,"_143":-5,"_247":299,"_26":300},{"_43":284,"_32":285,"_30":286,"_137":190,"_41":42,"_40":287,"_139":58,"_38":288,"_13":150,"_34":20,"_36":289,"_23":24,"_143":-5,"_247":290,"_26":291},{"_43":276,"_32":277,"_30":278,"_137":190,"_41":42,"_40":279,"_139":24,"_38":280,"_13":62,"_34":35,"_36":281,"_23":24,"_143":-5,"_247":282,"_26":283},{"_43":181,"_32":182,"_30":183,"_137":-5,"_41":42,"_40":184,"_139":58,"_38":273,"_13":62,"_34":186,"_36":-5,"_23":24,"_143":-5,"_247":274,"_26":275},{"_43":265,"_32":266,"_30":267,"_137":183,"_41":42,"_40":268,"_139":24,"_38":269,"_13":62,"_34":35,"_36":270,"_23":24,"_143":-5,"_247":271,"_26":272},{"_43":174,"_32":175,"_30":176,"_137":-5,"_41":42,"_40":177,"_139":58,"_38":262,"_13":62,"_34":20,"_36":179,"_23":24,"_143":-5,"_247":263,"_26":264},{"_43":167,"_32":168,"_30":169,"_137":-5,"_41":42,"_40":170,"_139":58,"_38":259,"_13":62,"_34":20,"_36":172,"_23":24,"_143":-5,"_247":260,"_26":261},{"_43":160,"_32":161,"_30":162,"_137":-5,"_41":42,"_40":163,"_139":24,"_38":256,"_13":62,"_34":20,"_36":165,"_23":24,"_143":-5,"_247":257,"_26":258},{"_43":153,"_32":154,"_30":155,"_137":-5,"_41":42,"_40":156,"_139":24,"_38":253,"_13":141,"_34":20,"_36":158,"_23":24,"_143":-5,"_247":254,"_26":255},{"_43":145,"_32":146,"_30":147,"_137":-5,"_41":42,"_40":148,"_139":24,"_38":250,"_13":150,"_34":20,"_36":151,"_23":24,"_143":-5,"_247":251,"_26":252},{"_43":134,"_32":135,"_30":136,"_137":-5,"_41":42,"_40":138,"_139":58,"_38":246,"_13":141,"_34":20,"_36":142,"_23":24,"_143":-5,"_247":248,"_26":249},["D",1763402806837],"children",[],[135],["D",1763411215247],[],[146],["D",1763411215215],[],[154],["D",1763404790641],[],[161],["D",1763401351018],[],[168],["D",1763401351042],[],[175],"cce74246-c3e4-11f0-b160-42dde27851f2","docTypes.ts","cce74336-c3e4-11f0-b160-42dde27851f2",36,["D",1763404790610],"/**\n * Shared documentation types for Val Town documentation generator\n * These types form the contract between the backend parser and frontend UI\n */\n\n/**\n * JSDoc-style comment information\n */\nexport interface DocComment {\n /** Raw comment text */\n raw: string;\n /** Parsed description */\n description: string;\n /** @param tags */\n params?: Array<{ name: string; type?: string; description: string }>;\n /** @returns tag */\n returns?: { type?: string; description: string };\n /** @example tags */\n examples?: string[];\n /** @deprecated tag */\n deprecated?: string;\n /** Other tags */\n tags?: Array<{ name: string; value: string }>;\n}\n\n/**\n * Parameter information for functions and methods\n */\nexport interface ParameterDoc {\n name: string;\n type: string;\n optional: boolean;\n defaultValue?: string;\n description?: string;\n}\n\n/**\n * Function or method documentation\n */\nexport interface FunctionDoc {\n kind: \"function\";\n name: string;\n signature: string;\n parameters: ParameterDoc[];\n returnType: string;\n isAsync: boolean;\n isExported: boolean;\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Class property documentation\n */\nexport interface PropertyDoc {\n name: string;\n type: string;\n isReadonly: boolean;\n isOptional: boolean;\n visibility: \"public\" | \"private\" | \"protected\";\n comment?: DocComment;\n}\n\n/**\n * Class method documentation\n */\nexport interface MethodDoc {\n name: string;\n signature: string;\n parameters: ParameterDoc[];\n returnType: string;\n isAsync: boolean;\n isStatic: boolean;\n visibility: \"public\" | \"private\" | \"protected\";\n comment?: DocComment;\n}\n\n/**\n * Class documentation\n */\nexport interface ClassDoc {\n kind: \"class\";\n name: string;\n isExported: boolean;\n isAbstract: boolean;\n extends?: string;\n implements?: string[];\n properties: PropertyDoc[];\n methods: MethodDoc[];\n constructor?: {\n parameters: ParameterDoc[];\n comment?: DocComment;\n };\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Interface property documentation\n */\nexport interface InterfacePropertyDoc {\n name: string;\n type: string;\n isOptional: boolean;\n isReadonly: boolean;\n comment?: DocComment;\n}\n\n/**\n * Interface method documentation\n */\nexport interface InterfaceMethodDoc {\n name: string;\n signature: string;\n parameters: ParameterDoc[];\n returnType: string;\n comment?: DocComment;\n}\n\n/**\n * Interface documentation\n */\nexport interface InterfaceDoc {\n kind: \"interface\";\n name: string;\n isExported: boolean;\n extends?: string[];\n properties: InterfacePropertyDoc[];\n methods: InterfaceMethodDoc[];\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Type alias documentation\n */\nexport interface TypeAliasDoc {\n kind: \"type\";\n name: string;\n type: string;\n isExported: boolean;\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Constant/variable documentation\n */\nexport interface ConstantDoc {\n kind: \"constant\";\n name: string;\n type: string;\n value?: string;\n isExported: boolean;\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Import statement information\n */\nexport interface ImportInfo {\n source: string;\n imports: Array<{\n name: string;\n alias?: string;\n isDefault?: boolean;\n isNamespace?: boolean;\n }>;\n location: { line: number; file: string };\n}\n\n/**\n * Val metadata from Val Town API\n */\nexport interface ValMetadata {\n id: string;\n name: string;\n author: {\n username: string;\n id: string;\n };\n version: string;\n privacy: \"public\" | \"private\" | \"unlisted\";\n createdAt: string;\n updatedAt: string;\n readme?: string;\n}\n\n/**\n * Main documentation manifest\n * This is the primary output of the parser and input to the UI\n */\nexport interface DocManifest {\n /** Val identifier (e.g., \"username/valname\") */\n val: string;\n /** Val version */\n version: string;\n /** ISO timestamp of generation */\n generatedAt: string;\n /** Parsed exports organized by kind */\n exports: {\n functions: FunctionDoc[];\n classes: ClassDoc[];\n interfaces: InterfaceDoc[];\n types: TypeAliasDoc[];\n constants: ConstantDoc[];\n };\n /** Import statements found in the val */\n imports: ImportInfo[];\n /** Metadata from Val Town API */\n metadata: ValMetadata;\n}\n\n/**\n * Type guard to check if value is a DocManifest\n */\nexport function isDocManifest(value: unknown): value is DocManifest {\n if (!value || typeof value !== \"object\") return false;\n const obj = value as Record;\n\n return (\n typeof obj.val === \"string\" &&\n typeof obj.version === \"string\" &&\n typeof obj.generatedAt === \"string\" &&\n typeof obj.exports === \"object\" &&\n obj.exports !== null &&\n Array.isArray((obj.exports as Record).functions) &&\n Array.isArray((obj.exports as Record).classes) &&\n Array.isArray((obj.exports as Record).interfaces) &&\n Array.isArray((obj.exports as Record).types) &&\n Array.isArray((obj.exports as Record).constants) &&\n Array.isArray(obj.imports) &&\n typeof obj.metadata === \"object\" &&\n obj.metadata !== null\n );\n}\n\n/**\n * Runtime validation that throws if value is not a DocManifest\n */\nexport function assertDocManifest(data: unknown): asserts data is DocManifest {\n if (!isDocManifest(data)) {\n throw new Error(\"Invalid DocManifest structure\");\n }\n}\n\n/**\n * Creates an empty DocManifest template\n */\nexport function createEmptyManifest(\n val: string,\n version: string,\n metadata: ValMetadata,\n): DocManifest {\n return {\n val,\n version,\n generatedAt: new Date().toISOString(),\n exports: {\n functions: [],\n classes: [],\n interfaces: [],\n types: [],\n constants: [],\n },\n imports: [],\n metadata,\n };\n}\n",[],[182,266],["D",1763404789566],[239],[182],"cc81206a-c3e4-11f0-8120-42dde27851f2","index.tsx","cc81213c-c3e4-11f0-8120-42dde27851f2",15,["D",1763404789941],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport React from \"https://esm.sh/react@18.2.0\";\nimport { createRoot } from \"https://esm.sh/react-dom@18.2.0/client\";\nimport { App } from \"./components/App.tsx\";\n\n// Get initial data injected by server\nconst initialData = (window as any).__INITIAL_DATA__ || {};\n\nconst root = createRoot(document.getElementById(\"root\")!);\nroot.render(\n \n \n \n);\n",[],[189,277],"a03dd340-c3f3-11f0-bbb3-42dde27851f2","index.html","cc8da1a0-c3e4-11f0-85f8-42dde27851f2",42,["D",1763411158044],"\n\n\n \n \n Val Town Documentation Generator\n\n \n \n\n \n \n\n \n\n\n

\n\n \n \n\n\n",[],[189,285],"ccf5eba2-c3e4-11f0-8a14-42dde27851f2","TypeDocCard.tsx","ccf5ec60-c3e4-11f0-8a14-42dde27851f2","cc53b332-c3e4-11f0-8a14-42dde27851f2",38,["D",1763404790069],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { TypeAliasDoc } from \"../../shared/docTypes.ts\";\nimport { CodeBlock } from \"./CodeBlock.tsx\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\nexport interface TypeDocCardProps {\n type: TypeAliasDoc;\n}\n\nexport function TypeDocCard(props: TypeDocCardProps) {\n const { type } = props;\n\n return (\n

\n type {type.name}\n

\n \n {type.location.file}:{type.location.line}\n \n

\n {type.isExported && (\n \n exported\n \n )}\n

\n\n {type.comment && }\n\n

Definition

\n \n

\n );\n}\n",[],[189,301,293],"components","ccbebc18-c3e4-11f0-85f8-42dde27851f2","Sidebar.tsx","ccbebcd6-c3e4-11f0-85f8-42dde27851f2",27,["D",1763404790343],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\n\nexport interface SidebarProps {\n manifest: DocManifest;\n searchQuery: string;\n}\n\nexport function Sidebar(props: SidebarProps) {\n const { manifest, searchQuery } = props;\n const query = searchQuery.toLowerCase();\n\n const filterBySearch = (name: string) => {\n if (!query) return true;\n return name.toLowerCase().includes(query);\n };\n\n const scrollToElement = (id: string) => {\n const element = document.getElementById(id);\n if (element) {\n element.scrollIntoView({ behavior: \"smooth\", block: \"start\" });\n }\n };\n\n return (\n

\n Val Info\n

{manifest.val}

v{manifest.version}

\n\n {manifest.exports.functions.length > 0 && (\n

\n Functions ({manifest.exports.functions.filter(f => filterBySearch(f.name)).length})\n

\n scrollToElement(`func-${func.name}`)}\n className=\"text-sm text-blue-600 hover:text-blue-800 hover:underline text-left w-full\"\n >\n {func.name}\n \n

\n )}\n\n {manifest.exports.classes.length > 0 && (\n

\n Classes ({manifest.exports.classes.filter(c => filterBySearch(c.name)).length})\n

\n scrollToElement(`class-${cls.name}`)}\n className=\"text-sm text-blue-600 hover:text-blue-800 hover:underline text-left w-full\"\n >\n {cls.name}\n \n

\n )}\n\n {manifest.exports.interfaces.length > 0 && (\n

\n Interfaces ({manifest.exports.interfaces.filter(i => filterBySearch(i.name)).length})\n

\n scrollToElement(`interface-${iface.name}`)}\n className=\"text-sm text-blue-600 hover:text-blue-800 hover:underline text-left w-full\"\n >\n {iface.name}\n \n

\n )}\n\n {manifest.exports.types.length > 0 && (\n

\n Types ({manifest.exports.types.filter(t => filterBySearch(t.name)).length})\n

\n scrollToElement(`type-${type.name}`)}\n className=\"text-sm text-blue-600 hover:text-blue-800 hover:underline text-left w-full\"\n >\n {type.name}\n \n

\n )}\n\n {manifest.exports.constants.length > 0 && (\n

\n Constants ({manifest.exports.constants.filter(c => filterBySearch(c.name)).length})\n

\n scrollToElement(`const-${constant.name}`)}\n className=\"text-sm text-blue-600 hover:text-blue-800 hover:underline text-left w-full\"\n >\n {constant.name}\n \n

\n )}\n

\n );\n}\n",[],[189,301,303],"ccb3c9b6-c3e4-11f0-b160-42dde27851f2","MainContent.tsx","ccb3ca7e-c3e4-11f0-b160-42dde27851f2",25,["D",1763404790262],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\nimport { FunctionDocCard } from \"./FunctionDocCard.tsx\";\nimport { ClassDocCard } from \"./ClassDocCard.tsx\";\nimport { InterfaceDocCard } from \"./InterfaceDocCard.tsx\";\nimport { TypeDocCard } from \"./TypeDocCard.tsx\";\nimport { ConstantDocCard } from \"./ConstantDocCard.tsx\";\n\nexport interface MainContentProps {\n manifest: DocManifest;\n searchQuery: string;\n}\n\nexport function MainContent(props: MainContentProps) {\n const { manifest, searchQuery } = props;\n const query = searchQuery.toLowerCase();\n\n const filterBySearch = (name: string) => {\n if (!query) return true;\n return name.toLowerCase().includes(query);\n };\n\n const filteredFunctions = manifest.exports.functions.filter((f) =>\n filterBySearch(f.name)\n );\n const filteredClasses = manifest.exports.classes.filter((c) =>\n filterBySearch(c.name)\n );\n const filteredInterfaces = manifest.exports.interfaces.filter((i) =>\n filterBySearch(i.name)\n );\n const filteredTypes = manifest.exports.types.filter((t) =>\n filterBySearch(t.name)\n );\n const filteredConstants = manifest.exports.constants.filter((c) =>\n filterBySearch(c.name)\n );\n\n const hasResults =\n filteredFunctions.length > 0 ||\n filteredClasses.length > 0 ||\n filteredInterfaces.length > 0 ||\n filteredTypes.length > 0 ||\n filteredConstants.length > 0;\n\n return (\n

\n {manifest.metadata.name}\n

\n by {manifest.metadata.author.username} • v{manifest.version}\n

\n {manifest.metadata.readme && (\n

{manifest.metadata.readme}

\n )}\n

\n\n {!hasResults && (\n

No results found for \"{searchQuery}\"

\n )}\n\n {filteredFunctions.length > 0 && (\n

Functions

\n {filteredFunctions.map((func) => (\n \n ))}\n

\n )}\n\n {filteredClasses.length > 0 && (\n

Classes

\n {filteredClasses.map((cls) => (\n \n ))}\n

\n )}\n\n {filteredInterfaces.length > 0 && (\n

Interfaces

\n {filteredInterfaces.map((iface) => (\n \n ))}\n

\n )}\n\n {filteredTypes.length > 0 && (\n

Type Aliases

\n {filteredTypes.map((type) => (\n \n ))}\n

\n )}\n\n {filteredConstants.length > 0 && (\n

Constants

\n {filteredConstants.map((constant) => (\n \n ))}\n

\n )}\n

\n );\n}\n",[],[189,301,311],"ccb126f2-c3e4-11f0-a716-42dde27851f2","LoadingSpinner.tsx","ccb1280a-c3e4-11f0-a716-42dde27851f2",24,["D",1763404790247],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nexport function LoadingSpinner() {\n return (\n

Generating documentation...

\n );\n}\n",[],[189,301,319],"ccaa9b16-c3e4-11f0-b9d5-42dde27851f2","InterfaceDocCard.tsx","ccaa9c1a-c3e4-11f0-b9d5-42dde27851f2",22,["D",1763404790212],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { InterfaceDoc } from \"../../shared/docTypes.ts\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\nexport interface InterfaceDocCardProps {\n iface: InterfaceDoc;\n}\n\nexport function InterfaceDocCard(props: InterfaceDocCardProps) {\n const { iface } = props;\n\n return (\n

\n interface {iface.name}\n

\n \n {iface.location.file}:{iface.location.line}\n \n {iface.extends && iface.extends.length > 0 && (\n

\n extends{\" \"}\n {iface.extends.map((ext, i) => (\n \n {ext}\n {i < iface.extends!.length - 1 && \", \"}\n \n ))}\n

\n )}\n

\n {iface.isExported && (\n \n exported\n \n )}\n

\n\n {iface.comment && }\n\n {iface.properties.length > 0 && (\n

Properties

\n {iface.properties.map((prop) => (\n

\n \n {prop.isReadonly && readonly }\n {prop.name}{prop.isOptional && \"?\"}: {prop.type}\n \n

\n {prop.comment && (\n

\n {prop.comment.description}\n

\n )}\n

\n ))}\n

\n )}\n\n {iface.methods.length > 0 && (\n

Methods

\n {iface.methods.map((method) => (\n

\n {method.name}(): {method.returnType}\n

\n {method.comment && (\n

\n {method.comment.description}\n

\n )}\n {method.parameters.length > 0 && (\n

\n Parameters: \n {method.parameters.map((param, i) => (\n \n {param.name}: {param.type}\n {i < method.parameters.length - 1 && \", \"}\n \n ))}\n

\n )}\n

\n ))}\n

\n )}\n

\n );\n}\n",[],[189,301,327],"ccba8878-c3e4-11f0-b9d5-42dde27851f2","Header.tsx","ccba8936-c3e4-11f0-b9d5-42dde27851f2",26,["D",1763404790317],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport { useState } from \"https://esm.sh/react@18.2.0\";\n\nexport interface HeaderProps {\n onSubmit: (val: string) => void;\n onRefresh: () => void;\n currentVal: string;\n onSearchChange: (query: string) => void;\n}\n\nexport function Header(props: HeaderProps) {\n const [inputVal, setInputVal] = useState(props.currentVal);\n\n const handleSubmit = (e: React.FormEvent) => {\n e.preventDefault();\n if (inputVal.trim()) {\n props.onSubmit(inputVal.trim());\n }\n };\n\n return (\n

\n 📚 Val Town Docs\n

\n {props.currentVal && (\n \n 🔄 Refresh\n \n )}\n

\n\n

\n \n\n {props.currentVal && (\n props.onSearchChange(e.target.value)}\n className=\"w-64 px-4 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500\"\n />\n )}\n

\n );\n}\n",[],[189,301,335],"cc9d0924-c3e4-11f0-85f8-42dde27851f2","FunctionDocCard.tsx","cc9d0a1e-c3e4-11f0-85f8-42dde27851f2",19,["D",1763404790124],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { FunctionDoc } from \"../../shared/docTypes.ts\";\nimport { CodeBlock } from \"./CodeBlock.tsx\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\nexport interface FunctionDocCardProps {\n func: FunctionDoc;\n}\n\nexport function FunctionDocCard(props: FunctionDocCardProps) {\n const { func } = props;\n\n return (\n

\n {func.isAsync && async }\n {func.name}\n

\n \n {func.location.file}:{func.location.line}\n \n

\n {func.isExported && (\n \n exported\n \n )}\n

\n\n {func.comment && }\n\n

Signature

\n \n

\n\n {func.parameters.length > 0 && (\n

Parameters

\n \n \n \n \n \n \n \n \n \n \n {func.parameters.map((param) => (\n \n \n \n \n \n \n ))}\n \n

Name	Type	Optional	Default
{param.name}	{param.type}	{param.optional ? \"Yes\" : \"No\"}	\n {param.defaultValue \|\| \"-\"}\n

\n )}\n\n

Returns

\n {func.returnType}\n

\n );\n}\n",[],[189,301,343],"cca3f91e-c3e4-11f0-83ba-42dde27851f2","ErrorMessage.tsx","cca3fa40-c3e4-11f0-83ba-42dde27851f2",21,["D",1763404790094],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nexport interface ErrorMessageProps {\n message: string;\n}\n\nexport function ErrorMessage(props: ErrorMessageProps) {\n return (\n

\n ❌\n

Error

{props.message}

\n );\n}\n",[],[189,301,351],"ccad401e-c3e4-11f0-85f8-42dde27851f2","DocCommentDisplay.tsx","ccad40e6-c3e4-11f0-85f8-42dde27851f2",23,["D",1763404790228],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { DocComment } from \"../../shared/docTypes.ts\";\n\nexport interface DocCommentDisplayProps {\n comment: DocComment;\n}\n\nexport function DocCommentDisplay(props: DocCommentDisplayProps) {\n const { comment } = props;\n\n return (\n

\n {comment.deprecated && (\n

\n ⚠️ Deprecated: \n {comment.deprecated}\n

\n )}\n\n {comment.description && (\n

{comment.description}

\n )}\n\n {comment.params && comment.params.length > 0 && (\n

\n Parameters\n

\n \n {param.name}\n \n {param.type && (\n ({param.type})\n )}\n {param.description && (\n - {param.description}\n )}\n

\n )}\n\n {comment.returns && (\n

\n Returns\n

\n {comment.returns.type && (\n \n {comment.returns.type}\n \n )}\n {comment.returns.description}\n

\n )}\n\n {comment.examples && comment.examples.length > 0 && (\n

\n Examples\n

\n {comment.examples.map((example, i) => (\n \n {example}\n \n ))}\n

\n )}\n

\n );\n}\n",[],[189,301,359],"cca0bc2c-c3e4-11f0-8120-42dde27851f2","ConstantDocCard.tsx","cca0bcea-c3e4-11f0-8120-42dde27851f2",20,["D",1763404789977],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { ConstantDoc } from \"../../shared/docTypes.ts\";\nimport { CodeBlock } from \"./CodeBlock.tsx\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\nexport interface ConstantDocCardProps {\n constant: ConstantDoc;\n}\n\nexport function ConstantDocCard(props: ConstantDocCardProps) {\n const { constant } = props;\n\n return (\n

\n {constant.name}\n

\n \n {constant.location.file}:{constant.location.line}\n \n

\n {constant.isExported && (\n \n exported\n \n )}\n

\n\n {constant.comment && }\n\n

\n Type: \n {constant.type}\n

\n\n {constant.value && (\n

Value

\n \n

\n )}\n

\n );\n}\n",[],[189,301,367],"cccaa1b8-c3e4-11f0-a716-42dde27851f2","CodeBlock.tsx","cccaa2b2-c3e4-11f0-a716-42dde27851f2",29,["D",1763404790347],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nexport interface CodeBlockProps {\n code: string;\n language?: string;\n}\n\nexport function CodeBlock(props: CodeBlockProps) {\n return (\n

\n      {props.code}\n

\n );\n}\n",[],[189,301,375],"cc959216-c3e4-11f0-982c-42dde27851f2","ClassDocCard.tsx","cc959324-c3e4-11f0-982c-42dde27851f2",18,["D",1763404789982],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { ClassDoc } from \"../../shared/docTypes.ts\";\nimport { CodeBlock } from \"./CodeBlock.tsx\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\nexport interface ClassDocCardProps {\n cls: ClassDoc;\n}\n\nexport function ClassDocCard(props: ClassDocCardProps) {\n const { cls } = props;\n\n return (\n

\n {cls.isAbstract && abstract }\n class {cls.name}\n

\n \n {cls.location.file}:{cls.location.line}\n \n {cls.extends && (\n

\n extends {cls.extends}\n

\n )}\n {cls.implements && cls.implements.length > 0 && (\n

\n implements{\" \"}\n {cls.implements.map((impl, i) => (\n \n {impl}\n {i < cls.implements!.length - 1 && \", \"}\n \n ))}\n

\n )}\n

\n {cls.isExported && (\n \n exported\n \n )}\n

\n\n {cls.comment && }\n\n {cls.constructor && (\n

Constructor

\n {cls.constructor.parameters.length > 0 && (\n \n \n \n \n \n \n \n \n {cls.constructor.parameters.map((param) => (\n \n \n \n \n ))}\n \n

Parameter	Type
{param.name}	{param.type}

\n )}\n

\n )}\n\n {cls.properties.length > 0 && (\n

Properties

\n {cls.properties.map((prop) => (\n

\n \n {prop.visibility !== \"public\" && (\n {prop.visibility} \n )}\n {prop.isReadonly && readonly }\n {prop.name}: {prop.type}\n \n {prop.isOptional && (\n optional\n )}\n

\n {prop.comment && (\n

\n {prop.comment.description}\n

\n )}\n

\n ))}\n

\n )}\n\n {cls.methods.length > 0 && (\n

Methods

\n {cls.methods.map((method) => (\n

\n {method.visibility !== \"public\" && (\n {method.visibility} \n )}\n {method.isStatic && static }\n {method.isAsync && async }\n {method.name}()\n

\n {method.comment && (\n

\n {method.comment.description}\n

\n )}\n

\n ))}\n

\n )}\n

\n );\n}\n",[],[189,301,383],"abb01782-c3f4-11f0-9ed4-42dde27851f2","App.tsx","cc86876c-c3e4-11f0-83ba-42dde27851f2",46,["D",1763411606827],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport { useState, useEffect } from \"https://esm.sh/react@18.2.0\";\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\nimport { Header } from \"./Header.tsx\";\nimport { Sidebar } from \"./Sidebar.tsx\";\nimport { MainContent } from \"./MainContent.tsx\";\nimport { ErrorMessage } from \"./ErrorMessage.tsx\";\nimport { LoadingSpinner } from \"./LoadingSpinner.tsx\";\n\nexport interface AppProps {\n initialManifest?: DocManifest;\n initialVal?: string;\n error?: string;\n}\n\nexport function App(props: AppProps) {\n const [manifest, setManifest] = useState(\n props.initialManifest || null,\n );\n const [val, setVal] = useState(props.initialVal || \"\");\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(props.error || null);\n const [searchQuery, setSearchQuery] = useState(\"\");\n\n // Fetch documentation for a val\n const fetchDocs = async (valIdentifier: string, refresh = false) => {\n if (!valIdentifier) return;\n\n console.log(`[fetchDocs] Requesting docs for val: ${valIdentifier}, refresh: ${refresh}`);\n setLoading(true);\n setError(null);\n\n try {\n const url = `/api/docs?val=${encodeURIComponent(valIdentifier)}${\n refresh ? \"&refresh=true\" : \"\"\n }`;\n console.log(`[fetchDocs] Fetching from URL: ${url}`);\n \n const response = await fetch(url);\n console.log(`[fetchDocs] Response status: ${response.status} ${response.statusText}`);\n\n if (!response.ok) {\n const errorData = await response.json();\n console.error(`[fetchDocs] Error response:`, errorData);\n throw new Error(errorData.message || \"Failed to fetch documentation\");\n }\n\n const data = await response.json();\n console.log(`[fetchDocs] Successfully fetched docs:`, data);\n setManifest(data);\n setVal(valIdentifier);\n\n // Update URL without reload\n const newUrl = `/?val=${encodeURIComponent(valIdentifier)}`;\n window.history.pushState({}, \"\", newUrl);\n } catch (err) {\n console.error(`[fetchDocs] Error caught:`, err);\n setError(err instanceof Error ? err.message : \"Unknown error\");\n setManifest(null);\n } finally {\n setLoading(false);\n }\n };\n\n // Handle val input submission\n const handleSubmit = (valIdentifier: string) => {\n fetchDocs(valIdentifier, false);\n };\n\n // Handle refresh\n const handleRefresh = () => {\n if (val) {\n fetchDocs(val, true);\n }\n };\n\n return (\n

\n \n\n {error && (\n

\n \n

\n )}\n\n {loading && (\n

\n \n

\n )}\n\n {!loading && !error && manifest && (\n

\n \n \n

\n )}\n\n {!loading && !error && !manifest && (\n

\n Val Town Documentation Generator\n

\n Enter a val identifier (e.g., \"username/valname\") above to generate\n documentation\n

Features

\n 📝\n Automatic extraction of functions, classes, interfaces, types, and constants\n
\n 💬\n JSDoc comment parsing with @param, @returns, and @example tags\n
\n 🔍\n Search and filter functionality\n
\n ⚡\n Fast caching for quick subsequent loads\n
\n 🎨\n Clean, responsive UI with syntax highlighting\n

\n )}\n

\n );\n}\n",[],[189,301,391],"cc53b27e-c3e4-11f0-8a14-42dde27851f2",12,["D",1763404789643],[223,224,225,226,227,228,229,230,231,232,233,234,235],[189,301],["D",1763404789368],[222,236,237],[189],"0ee6d14a-c3f7-11f0-be52-42dde27851f2",["D",1763412632276],[],[195,33],"ccc2aff8-c3e4-11f0-b160-42dde27851f2","docGenerator.http.ts",28,["D",1763404790370],"http","/**\n * Val Town Documentation Generator\n * Main HTTP val entry point\n *\n * Provides:\n * - GET / - Documentation viewer UI\n * - GET /api/docs?val=username/valname - JSON API for documentation\n * - GET /frontend/* - Static frontend assets\n * - GET /shared/* - Shared module assets\n */\n\nimport { Hono } from \"npm:hono@4.0.0\";\nimport { serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport { getApiDocs } from \"./routes/apiDocs.ts\";\nimport { getUI } from \"./routes/ui.ts\";\n\nconst app = new Hono();\n\n// Unwrap Hono errors to see original error details\napp.onError((err, c) => {\n throw err;\n});\n\n/**\n * API Routes\n */\napp.get(\"/api/docs\", getApiDocs);\n\n/**\n * UI Routes\n */\napp.get(\"/\", getUI);\n\n/**\n * Static File Serving\n */\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 * Health check endpoint\n */\napp.get(\"/health\", (c) => {\n return c.json({\n status: \"ok\",\n timestamp: new Date().toISOString(),\n });\n});\n\n/**\n * 404 handler\n */\napp.notFound((c) => {\n return c.json(\n {\n error: \"NOT_FOUND\",\n message: \"Route not found\",\n availableRoutes: [\n \"GET /\",\n \"GET /api/docs?val=username/valname\",\n \"GET /health\",\n ],\n },\n 404,\n );\n});\n\n// Export the Hono app as the HTTP val entry point\nexport default app.fetch;\n",[],[195,411],"dae3cb3c-c3f6-11f0-b4fc-42dde27851f2","valFetcher.ts","ccdc741a-c3e4-11f0-b1eb-42dde27851f2","cc70008c-c3e4-11f0-8120-42dde27851f2",58,["D",1763412545012],14,"/**\n * Val Town API client for fetching val metadata and source code\n * Uses the official @valtown/sdk for API interactions\n */\n\nimport ValTown from \"npm:@valtown/sdk\";\nimport type { ValMetadata } from \"../../shared/docTypes.ts\";\n\n/**\n * Represents a file in a val bundle\n */\nexport interface ValFile {\n path: string;\n content: string;\n}\n\n/**\n * Complete val bundle with metadata and source files\n */\nexport interface ValBundle {\n metadata: ValMetadata;\n files: ValFile[];\n version: string;\n}\n\n/**\n * Parse val identifier into username and val name\n */\nexport function parseValIdentifier(val: string): {\n username: string;\n valname: string;\n} {\n const parts = val.split(\"/\");\n if (parts.length !== 2) {\n throw new Error(\n `Invalid val identifier \"${val}\". Expected format: username/valname`,\n );\n }\n return { username: parts[0], valname: parts[1] };\n}\n\n/**\n * Fetch val metadata using the official Val Town SDK\n */\nasync function fetchValMetadata(\n client: ValTown,\n username: string,\n valname: string,\n): Promise {\n try {\n // Use the SDK's alias retrieve method to fetch val metadata\n console.log(\n `[valFetchr] calling client.alias.username.valName.retrieve(${valname}, {\n username: ${username}`,\n );\n const val = await client.alias.username.valName.retrieve(valname, {\n username,\n });\n\n // Map SDK response to our ValMetadata format\n return {\n id: val.id,\n name: val.name,\n author: {\n username: val.author?.username || username,\n id: val.author?.id || \"\",\n },\n version: String(val.version || \"1\"),\n privacy: val.privacy || \"public\",\n createdAt: val.createdAt,\n updatedAt: val.updatedAt,\n readme: val.readme,\n };\n } catch (error) {\n if (error instanceof ValTown.NotFoundError) {\n throw new Error(\n `Val not found: ${username}/${valname} (looked for v:${valname}, u:${username} `,\n );\n }\n throw new Error(`Failed to fetch val metadata: ${error.message}`);\n }\n}\n\n/**\n * Fetch val source code using the official Val Town SDK\n */\nasync function fetchValSource(\n client: ValTown,\n valId: string,\n): Promise {\n try {\n // Use the SDK's files.getContent method to fetch val source code\n const response = await client.vals.files.getContent(valId);\n\n // The response is a blob/stream, convert it to text\n return await response.text();\n } catch (error) {\n throw new Error(`Failed to fetch val source: ${error.message}`);\n }\n}\n\n/**\n * Main Val fetcher interface\n */\nexport interface ValFetcher {\n fetchLatest(val: string): Promise;\n}\n\n/**\n * Create a Val Town API fetcher using the official SDK\n */\nexport function createValFetcher(): ValFetcher {\n // Initialize the Val Town SDK client\n // The SDK automatically uses VAL_TOWN_API_KEY environment variable if available\n const client = new ValTown();\n\n return {\n async fetchLatest(val: string): Promise {\n const { username, valname } = parseValIdentifier(val);\n\n // Fetch metadata first using the SDK\n const metadata = await fetchValMetadata(client, username, valname);\n\n // Fetch source code using the SDK\n const source = await fetchValSource(client, metadata.id);\n\n // For now, we treat the val as a single file\n // In the future, we could support multi-file vals/projects\n const files: ValFile[] = [\n {\n path: `${valname}.ts`,\n content: source,\n },\n ];\n\n return {\n metadata,\n files,\n version: metadata.version,\n };\n },\n };\n}\n\n/**\n * Default val fetcher instance\n */\nexport const valFetcher = createValFetcher();",[],[195,428,419],"services","ccd3c46e-c3e4-11f0-83ba-42dde27851f2","tsParser.ts","ccd3c522-c3e4-11f0-83ba-42dde27851f2",31,["D",1763404790480],"/**\n * TypeScript AST parser for extracting documentation\n * Uses the TypeScript Compiler API to walk the AST and extract exports\n */\n\nimport * as ts from \"npm:typescript@5.3.3\";\nimport type {\n ClassDoc,\n ConstantDoc,\n DocComment,\n DocManifest,\n FunctionDoc,\n ImportInfo,\n InterfaceDoc,\n InterfaceMethodDoc,\n InterfacePropertyDoc,\n MethodDoc,\n ParameterDoc,\n PropertyDoc,\n TypeAliasDoc,\n ValMetadata,\n} from \"../../shared/docTypes.ts\";\nimport type { ValBundle } from \"./valFetcher.ts\";\nimport { createEmptyManifest } from \"../../shared/docTypes.ts\";\n\n/**\n * Parse JSDoc comment from a node\n */\nfunction parseJSDocComment(\n node: ts.Node,\n sourceFile: ts.SourceFile,\n): DocComment | undefined {\n const jsDocTags = ts.getJSDocTags(node);\n const jsDocComments = (node as { jsDoc?: ts.JSDoc[] }).jsDoc;\n\n if (!jsDocComments || jsDocComments.length === 0) {\n return undefined;\n }\n\n const comment = jsDocComments[0];\n const commentText = comment.comment;\n const description =\n typeof commentText === \"string\"\n ? commentText\n : commentText\n ? commentText.map((part) => part.text).join(\"\")\n : \"\";\n\n const docComment: DocComment = {\n raw: comment.getText(sourceFile),\n description: description.trim(),\n };\n\n // Parse @param tags\n const paramTags = jsDocTags.filter((tag) => tag.tagName.text === \"param\");\n if (paramTags.length > 0) {\n docComment.params = paramTags.map((tag) => {\n const name = tag.comment\n ? String(tag.comment).split(\" \")[0]\n : \"\";\n const desc = tag.comment\n ? String(tag.comment).substring(name.length).trim()\n : \"\";\n return {\n name,\n type: undefined,\n description: desc,\n };\n });\n }\n\n // Parse @returns tag\n const returnTag = jsDocTags.find((tag) => tag.tagName.text === \"returns\");\n if (returnTag && returnTag.comment) {\n docComment.returns = {\n description: String(returnTag.comment),\n };\n }\n\n // Parse @example tags\n const exampleTags = jsDocTags.filter((tag) => tag.tagName.text === \"example\");\n if (exampleTags.length > 0) {\n docComment.examples = exampleTags.map((tag) =>\n tag.comment ? String(tag.comment) : \"\"\n );\n }\n\n // Parse @deprecated tag\n const deprecatedTag = jsDocTags.find((tag) =>\n tag.tagName.text === \"deprecated\"\n );\n if (deprecatedTag) {\n docComment.deprecated = deprecatedTag.comment\n ? String(deprecatedTag.comment)\n : \"This is deprecated\";\n }\n\n return docComment;\n}\n\n/**\n * Get type as string from type node\n */\nfunction getTypeString(\n typeNode: ts.TypeNode | undefined,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): string {\n if (!typeNode) return \"any\";\n return typeNode.getText(sourceFile);\n}\n\n/**\n * Parse parameter documentation\n */\nfunction parseParameters(\n parameters: ts.NodeArray,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): ParameterDoc[] {\n return parameters.map((param) => {\n const name = param.name.getText(sourceFile);\n const type = getTypeString(param.type, checker, sourceFile);\n const optional = !!param.questionToken || !!param.initializer;\n const defaultValue = param.initializer?.getText(sourceFile);\n\n return {\n name,\n type,\n optional,\n defaultValue,\n };\n });\n}\n\n/**\n * Parse function declaration or expression\n */\nfunction parseFunctionDeclaration(\n node: ts.FunctionDeclaration | ts.VariableStatement,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): FunctionDoc | null {\n let funcDecl: ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;\n let name: string;\n let isExported = false;\n\n if (ts.isFunctionDeclaration(node)) {\n funcDecl = node;\n name = node.name?.getText(sourceFile) || \"anonymous\";\n isExported = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ExportKeyword\n ));\n } else if (ts.isVariableStatement(node)) {\n // Handle: export const foo = () => {}\n isExported = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ExportKeyword\n ));\n\n const declaration = node.declarationList.declarations[0];\n if (!declaration?.initializer) return null;\n\n if (\n !ts.isArrowFunction(declaration.initializer) &&\n !ts.isFunctionExpression(declaration.initializer)\n ) {\n return null;\n }\n\n funcDecl = declaration.initializer;\n name = declaration.name.getText(sourceFile);\n } else {\n return null;\n }\n\n const signature = funcDecl.getText(sourceFile);\n const parameters = parseParameters(\n funcDecl.parameters,\n checker,\n sourceFile,\n );\n const returnType = getTypeString(funcDecl.type, checker, sourceFile);\n const isAsync = !!(funcDecl.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.AsyncKeyword\n ));\n const comment = parseJSDocComment(node, sourceFile);\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart())\n .line + 1;\n\n return {\n kind: \"function\",\n name,\n signature,\n parameters,\n returnType,\n isAsync,\n isExported,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse class property\n */\nfunction parseProperty(\n node: ts.PropertyDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): PropertyDoc {\n const name = node.name.getText(sourceFile);\n const type = getTypeString(node.type, checker, sourceFile);\n const isReadonly = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ReadonlyKeyword\n ));\n const isOptional = !!node.questionToken;\n\n let visibility: \"public\" | \"private\" | \"protected\" = \"public\";\n if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword)) {\n visibility = \"private\";\n } else if (\n node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ProtectedKeyword)\n ) {\n visibility = \"protected\";\n }\n\n const comment = parseJSDocComment(node, sourceFile);\n\n return {\n name,\n type,\n isReadonly,\n isOptional,\n visibility,\n comment,\n };\n}\n\n/**\n * Parse class method\n */\nfunction parseMethod(\n node: ts.MethodDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): MethodDoc {\n const name = node.name.getText(sourceFile);\n const signature = node.getText(sourceFile);\n const parameters = parseParameters(node.parameters, checker, sourceFile);\n const returnType = getTypeString(node.type, checker, sourceFile);\n const isAsync = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.AsyncKeyword\n ));\n const isStatic = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.StaticKeyword\n ));\n\n let visibility: \"public\" | \"private\" | \"protected\" = \"public\";\n if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword)) {\n visibility = \"private\";\n } else if (\n node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ProtectedKeyword)\n ) {\n visibility = \"protected\";\n }\n\n const comment = parseJSDocComment(node, sourceFile);\n\n return {\n name,\n signature,\n parameters,\n returnType,\n isAsync,\n isStatic,\n visibility,\n comment,\n };\n}\n\n/**\n * Parse class declaration\n */\nfunction parseClassDeclaration(\n node: ts.ClassDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): ClassDoc | null {\n const name = node.name?.getText(sourceFile);\n if (!name) return null;\n\n const isExported = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ExportKeyword\n ));\n const isAbstract = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.AbstractKeyword\n ));\n\n const extendsClause = node.heritageClauses?.find((c) =>\n c.token === ts.SyntaxKind.ExtendsKeyword\n );\n const extendsType = extendsClause?.types[0]?.getText(sourceFile);\n\n const implementsClause = node.heritageClauses?.find((c) =>\n c.token === ts.SyntaxKind.ImplementsKeyword\n );\n const implementsTypes = implementsClause?.types.map((t) =>\n t.getText(sourceFile)\n );\n\n const properties: PropertyDoc[] = [];\n const methods: MethodDoc[] = [];\n let constructor: ClassDoc[\"constructor\"];\n\n for (const member of node.members) {\n if (ts.isPropertyDeclaration(member)) {\n properties.push(parseProperty(member, checker, sourceFile));\n } else if (ts.isMethodDeclaration(member)) {\n methods.push(parseMethod(member, checker, sourceFile));\n } else if (ts.isConstructorDeclaration(member)) {\n constructor = {\n parameters: parseParameters(member.parameters, checker, sourceFile),\n comment: parseJSDocComment(member, sourceFile),\n };\n }\n }\n\n const comment = parseJSDocComment(node, sourceFile);\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart())\n .line + 1;\n\n return {\n kind: \"class\",\n name,\n isExported,\n isAbstract,\n extends: extendsType,\n implements: implementsTypes,\n properties,\n methods,\n constructor,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse interface property\n */\nfunction parseInterfaceProperty(\n node: ts.PropertySignature,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): InterfacePropertyDoc {\n const name = node.name.getText(sourceFile);\n const type = getTypeString(node.type, checker, sourceFile);\n const isOptional = !!node.questionToken;\n const isReadonly = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ReadonlyKeyword\n ));\n const comment = parseJSDocComment(node, sourceFile);\n\n return {\n name,\n type,\n isOptional,\n isReadonly,\n comment,\n };\n}\n\n/**\n * Parse interface method\n */\nfunction parseInterfaceMethod(\n node: ts.MethodSignature,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): InterfaceMethodDoc {\n const name = node.name.getText(sourceFile);\n const signature = node.getText(sourceFile);\n const parameters = parseParameters(node.parameters, checker, sourceFile);\n const returnType = getTypeString(node.type, checker, sourceFile);\n const comment = parseJSDocComment(node, sourceFile);\n\n return {\n name,\n signature,\n parameters,\n returnType,\n comment,\n };\n}\n\n/**\n * Parse interface declaration\n */\nfunction parseInterfaceDeclaration(\n node: ts.InterfaceDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): InterfaceDoc {\n const name = node.name.getText(sourceFile);\n const isExported = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ExportKeyword\n ));\n\n const extendsTypes = node.heritageClauses\n ?.find((c) => c.token === ts.SyntaxKind.ExtendsKeyword)\n ?.types.map((t) => t.getText(sourceFile));\n\n const properties: InterfacePropertyDoc[] = [];\n const methods: InterfaceMethodDoc[] = [];\n\n for (const member of node.members) {\n if (ts.isPropertySignature(member)) {\n properties.push(parseInterfaceProperty(member, checker, sourceFile));\n } else if (ts.isMethodSignature(member)) {\n methods.push(parseInterfaceMethod(member, checker, sourceFile));\n }\n }\n\n const comment = parseJSDocComment(node, sourceFile);\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart())\n .line + 1;\n\n return {\n kind: \"interface\",\n name,\n isExported,\n extends: extendsTypes,\n properties,\n methods,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse type alias declaration\n */\nfunction parseTypeAliasDeclaration(\n node: ts.TypeAliasDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): TypeAliasDoc {\n const name = node.name.getText(sourceFile);\n const type = node.type.getText(sourceFile);\n const isExported = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ExportKeyword\n ));\n const comment = parseJSDocComment(node, sourceFile);\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart())\n .line + 1;\n\n return {\n kind: \"type\",\n name,\n type,\n isExported,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse constant/variable declaration\n */\nfunction parseConstantDeclaration(\n node: ts.VariableStatement,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): ConstantDoc | null {\n const declaration = node.declarationList.declarations[0];\n if (!declaration) return null;\n\n // Skip if this is actually a function (handled elsewhere)\n if (\n declaration.initializer &&\n (ts.isArrowFunction(declaration.initializer) ||\n ts.isFunctionExpression(declaration.initializer))\n ) {\n return null;\n }\n\n const name = declaration.name.getText(sourceFile);\n const type = declaration.type\n ? getTypeString(declaration.type, checker, sourceFile)\n : checker.typeToString(\n checker.getTypeAtLocation(declaration),\n );\n const value = declaration.initializer?.getText(sourceFile);\n const isExported = !!(node.modifiers?.some((m) =>\n m.kind === ts.SyntaxKind.ExportKeyword\n ));\n const comment = parseJSDocComment(node, sourceFile);\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart())\n .line + 1;\n\n return {\n kind: \"constant\",\n name,\n type,\n value,\n isExported,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse import declaration\n */\nfunction parseImportDeclaration(\n node: ts.ImportDeclaration,\n sourceFile: ts.SourceFile,\n): ImportInfo {\n const source = (node.moduleSpecifier as ts.StringLiteral).text;\n const imports: ImportInfo[\"imports\"] = [];\n\n if (node.importClause) {\n // Default import\n if (node.importClause.name) {\n imports.push({\n name: node.importClause.name.getText(sourceFile),\n isDefault: true,\n });\n }\n\n // Named imports\n if (node.importClause.namedBindings) {\n if (ts.isNamespaceImport(node.importClause.namedBindings)) {\n // import * as foo\n imports.push({\n name: node.importClause.namedBindings.name.getText(sourceFile),\n isNamespace: true,\n });\n } else if (ts.isNamedImports(node.importClause.namedBindings)) {\n // import { a, b as c }\n for (const element of node.importClause.namedBindings.elements) {\n imports.push({\n name: element.name.getText(sourceFile),\n alias: element.propertyName?.getText(sourceFile),\n });\n }\n }\n }\n }\n\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart())\n .line + 1;\n\n return {\n source,\n imports,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse a Val bundle and extract documentation\n */\nexport function parseValBundle(bundle: ValBundle): DocManifest {\n const manifest = createEmptyManifest(\n `${bundle.metadata.author.username}/${bundle.metadata.name}`,\n bundle.version,\n bundle.metadata,\n );\n\n // Create an in-memory compiler host\n const files = new Map();\n for (const file of bundle.files) {\n files.set(file.path, file.content);\n }\n\n const compilerOptions: ts.CompilerOptions = {\n target: ts.ScriptTarget.ES2020,\n module: ts.ModuleKind.ESNext,\n lib: [\"lib.es2020.d.ts\", \"lib.dom.d.ts\"],\n allowJs: true,\n checkJs: false,\n strict: false,\n };\n\n const compilerHost: ts.CompilerHost = {\n getSourceFile: (fileName) => {\n const content = files.get(fileName);\n if (content !== undefined) {\n return ts.createSourceFile(\n fileName,\n content,\n ts.ScriptTarget.ES2020,\n true,\n );\n }\n return undefined;\n },\n writeFile: () => {},\n getCurrentDirectory: () => \"/\",\n getDirectories: () => [],\n fileExists: (fileName) => files.has(fileName),\n readFile: (fileName) => files.get(fileName),\n getCanonicalFileName: (fileName) => fileName,\n useCaseSensitiveFileNames: () => true,\n getNewLine: () => \"\\n\",\n getDefaultLibFileName: (options) => ts.getDefaultLibFileName(options),\n };\n\n // Create program\n const program = ts.createProgram(\n Array.from(files.keys()),\n compilerOptions,\n compilerHost,\n );\n const checker = program.getTypeChecker();\n\n // Walk AST for each file\n for (const sourceFile of program.getSourceFiles()) {\n if (!files.has(sourceFile.fileName)) continue;\n\n ts.forEachChild(sourceFile, (node) => {\n // Functions\n if (ts.isFunctionDeclaration(node)) {\n const func = parseFunctionDeclaration(node, checker, sourceFile);\n if (func) manifest.exports.functions.push(func);\n }\n\n // Variable statements (might be functions or constants)\n if (ts.isVariableStatement(node)) {\n const func = parseFunctionDeclaration(node, checker, sourceFile);\n if (func) {\n manifest.exports.functions.push(func);\n } else {\n const constant = parseConstantDeclaration(node, checker, sourceFile);\n if (constant) manifest.exports.constants.push(constant);\n }\n }\n\n // Classes\n if (ts.isClassDeclaration(node)) {\n const cls = parseClassDeclaration(node, checker, sourceFile);\n if (cls) manifest.exports.classes.push(cls);\n }\n\n // Interfaces\n if (ts.isInterfaceDeclaration(node)) {\n const iface = parseInterfaceDeclaration(node, checker, sourceFile);\n manifest.exports.interfaces.push(iface);\n }\n\n // Type aliases\n if (ts.isTypeAliasDeclaration(node)) {\n const type = parseTypeAliasDeclaration(node, checker, sourceFile);\n manifest.exports.types.push(type);\n }\n\n // Imports\n if (ts.isImportDeclaration(node)) {\n const imp = parseImportDeclaration(node, sourceFile);\n manifest.imports.push(imp);\n }\n });\n }\n\n return manifest;\n}\n",[],[195,428,430],"cce25bbe-c3e4-11f0-b160-42dde27851f2","docService.ts","cce25c68-c3e4-11f0-b160-42dde27851f2",35,["D",1763404790567],"/**\n * Documentation generation service\n * Orchestrates fetching, parsing, and caching of val documentation\n */\n\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\nimport { valFetcher } from \"./valFetcher.ts\";\nimport { deriveCacheKey, docCache } from \"./docCache.ts\";\nimport { parseValBundle } from \"./tsParser.ts\";\n\n/**\n * Cached documentation payload\n */\nexport interface CachedDocPayload {\n manifest: DocManifest;\n ssrHtml?: string;\n cachedAt: number;\n}\n\n/**\n * Generation options\n */\nexport interface GenerateDocsOptions {\n /** Force refresh, bypassing cache */\n refresh?: boolean;\n}\n\n/**\n * Generate documentation for a val\n * This is the main entry point for the documentation generation pipeline\n */\nexport async function generateDocs(\n val: string,\n opts: GenerateDocsOptions = {},\n): Promise {\n const cacheKey = deriveCacheKey(val);\n\n // Check cache unless refresh is requested\n if (!opts.refresh) {\n const cached = await docCache.get(cacheKey);\n if (cached) {\n console.log(`[doc-service] Cache hit for ${val}`);\n return cached;\n }\n }\n\n console.log(`[doc-service] Cache miss for ${val}, generating docs...`);\n\n // Fetch val bundle from Val Town API\n const bundle = await valFetcher.fetchLatest(val);\n\n // Parse TypeScript to extract documentation\n const manifest = parseValBundle(bundle);\n\n // Create payload\n const payload: CachedDocPayload = {\n manifest,\n cachedAt: Date.now(),\n };\n\n // Cache for future requests\n await docCache.set(cacheKey, payload, { version: bundle.version });\n\n console.log(\n `[doc-service] Generated and cached docs for ${val}@${bundle.version}`,\n );\n\n return payload;\n}\n\n/**\n * Refresh documentation in the cache\n */\nexport async function refreshDocs(val: string): Promise {\n return generateDocs(val, { refresh: true });\n}\n\n/**\n * Get cached documentation without generating\n */\nexport async function getCachedDocs(\n val: string,\n): Promise {\n const cacheKey = deriveCacheKey(val);\n return await docCache.get(cacheKey);\n}\n\n/**\n * Update SSR HTML in cache\n */\nexport async function updateCachedHtml(\n val: string,\n html: string,\n): Promise {\n const cacheKey = deriveCacheKey(val);\n const cached = await docCache.get(cacheKey);\n\n if (cached) {\n cached.ssrHtml = html;\n await docCache.set(cacheKey, cached, {\n version: cached.manifest.version,\n });\n }\n}\n\n/**\n * Clear documentation cache for a specific val\n */\nexport async function clearValCache(val: string): Promise {\n const cacheKey = deriveCacheKey(val);\n await docCache.delete(cacheKey);\n console.log(`[doc-service] Cleared cache for ${val}`);\n}\n\n/**\n * Clear all documentation caches\n */\nexport async function clearAllCaches(): Promise {\n await docCache.clear();\n console.log(\"[doc-service] Cleared all documentation caches\");\n}\n",[],[195,428,438],"ccdfd2d6-c3e4-11f0-a716-42dde27851f2","docCache.ts","ccdfd38a-c3e4-11f0-a716-42dde27851f2",34,["D",1763404790530],"/**\n * Documentation cache using Val Town blob storage with in-memory front cache\n */\n\nimport { blob } from \"https://esm.town/v/std/blob\";\n\n/**\n * Cache entry metadata\n */\nexport interface CacheEntry {\n data: T;\n version: string;\n cachedAt: number;\n expiresAt: number;\n}\n\n/**\n * Cache configuration\n */\nexport interface CacheConfig {\n /** Cache TTL in milliseconds (default: 1 hour) */\n ttlMs?: number;\n /** Blob key prefix (default: \"doc-cache\") */\n blobPrefix?: string;\n}\n\n/**\n * Documentation cache interface\n */\nexport interface DocCache {\n get(key: string): Promise;\n set(key: string, data: T, metadata: { version: string }): Promise;\n has(key: string): Promise;\n isExpired(key: string): Promise;\n delete(key: string): Promise;\n clear(): Promise;\n}\n\n/**\n * In-memory cache with LRU eviction\n */\nclass MemoryCache {\n private cache = new Map>();\n private readonly maxSize: number;\n\n constructor(maxSize = 100) {\n this.maxSize = maxSize;\n }\n\n get(key: string): CacheEntry | null {\n const entry = this.cache.get(key) as CacheEntry | undefined;\n if (!entry) return null;\n\n // Move to end (most recently used)\n this.cache.delete(key);\n this.cache.set(key, entry);\n\n return entry;\n }\n\n set(key: string, entry: CacheEntry): void {\n // Remove if exists (to update position)\n if (this.cache.has(key)) {\n this.cache.delete(key);\n }\n\n // Evict oldest if at capacity\n if (this.cache.size >= this.maxSize) {\n const firstKey = this.cache.keys().next().value;\n if (firstKey !== undefined) {\n this.cache.delete(firstKey);\n }\n }\n\n this.cache.set(key, entry);\n }\n\n has(key: string): boolean {\n return this.cache.has(key);\n }\n\n delete(key: string): void {\n this.cache.delete(key);\n }\n\n clear(): void {\n this.cache.clear();\n }\n}\n\n/**\n * Create a documentation cache instance\n */\nexport function createDocCache(config: CacheConfig = {}): DocCache {\n const ttlMs = config.ttlMs ?? 60 * 60 * 1000; // 1 hour default\n const blobPrefix = config.blobPrefix ?? \"doc-cache\";\n const memoryCache = new MemoryCache(100);\n\n function deriveBlobKey(key: string): string {\n return `${blobPrefix}:${key}`;\n }\n\n return {\n async get(key: string): Promise {\n const now = Date.now();\n\n // Check memory cache first\n const memEntry = memoryCache.get(key);\n if (memEntry && memEntry.expiresAt > now) {\n return memEntry.data;\n }\n\n // Fall back to blob storage\n const blobKey = deriveBlobKey(key);\n const blobEntry = await blob.getJSON(blobKey) as CacheEntry | null;\n\n if (!blobEntry) {\n return null;\n }\n\n // Check if expired\n if (blobEntry.expiresAt <= now) {\n // Clean up expired entry\n await blob.delete(blobKey);\n memoryCache.delete(key);\n return null;\n }\n\n // Populate memory cache\n memoryCache.set(key, blobEntry);\n\n return blobEntry.data;\n },\n\n async set(\n key: string,\n data: T,\n metadata: { version: string },\n ): Promise {\n const now = Date.now();\n const entry: CacheEntry = {\n data,\n version: metadata.version,\n cachedAt: now,\n expiresAt: now + ttlMs,\n };\n\n // Store in both memory and blob\n memoryCache.set(key, entry);\n await blob.setJSON(deriveBlobKey(key), entry);\n },\n\n async has(key: string): Promise {\n // Check memory first\n if (memoryCache.has(key)) {\n const entry = memoryCache.get(key);\n if (entry && entry.expiresAt > Date.now()) {\n return true;\n }\n }\n\n // Check blob\n const blobKey = deriveBlobKey(key);\n const blobEntry = await blob.getJSON(blobKey) as CacheEntry |\n null;\n\n if (!blobEntry) {\n return false;\n }\n\n return blobEntry.expiresAt > Date.now();\n },\n\n async isExpired(key: string): Promise {\n const hasKey = await this.has(key);\n return !hasKey;\n },\n\n async delete(key: string): Promise {\n memoryCache.delete(key);\n await blob.delete(deriveBlobKey(key));\n },\n\n async clear(): Promise {\n memoryCache.clear();\n // List and delete all blob entries with our prefix\n const keys = await blob.list(blobPrefix);\n await Promise.all(keys.map((key) => blob.delete(key)));\n },\n };\n}\n\n/**\n * Derive cache key from val identifier and version\n */\nexport function deriveCacheKey(val: string, version?: string): string {\n const normalized = val.toLowerCase().replace(/[^a-z0-9_/-]/g, \"_\");\n return version ? `${normalized}@${version}` : normalized;\n}\n\n/**\n * Default doc cache instance with 1 hour TTL\n */\nexport const docCache = createDocCache({\n ttlMs: 60 * 60 * 1000,\n blobPrefix: \"doc-manifest\",\n});\n",[],[195,428,446],"cc6fffce-c3e4-11f0-8120-42dde27851f2",["D",1763404789828],[215,216,217,218],[195,428],"ccda4a1e-c3e4-11f0-b160-42dde27851f2","ui.ts","ccda4afa-c3e4-11f0-b160-42dde27851f2","cc62307e-c3e4-11f0-8120-42dde27851f2",32,["D",1763404790450],"/**\n * UI routes for serving the documentation viewer\n */\n\nimport type { Context } from \"npm:hono@4.0.0\";\nimport { readFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport { generateDocs, updateCachedHtml } from \"../services/docService.ts\";\n\n/**\n * Render the HTML page with optional initial data\n */\nasync function renderIndexPage(data: {\n manifest?: unknown;\n val?: string;\n error?: string;\n}): Promise {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n\n // Inject initial data to avoid extra round-trips\n const dataScript = ``;\n\n html = html.replace(\"\", `${dataScript}`);\n\n return html;\n}\n\n/**\n * GET /\n * Serves the documentation viewer UI\n */\nexport async function getUI(c: Context) {\n const initialVal = c.req.query(\"val\");\n\n // If no val specified, show empty UI\n if (!initialVal) {\n const html = await renderIndexPage({});\n return c.html(html);\n }\n\n try {\n // Try to get cached docs\n const cached = await generateDocs(initialVal, { refresh: false });\n\n // Check if we have cached SSR HTML\n if (cached.ssrHtml) {\n return c.html(cached.ssrHtml);\n }\n\n // Generate HTML with initial manifest\n const html = await renderIndexPage({\n manifest: cached.manifest,\n val: initialVal,\n });\n\n // Cache the HTML for next time\n await updateCachedHtml(initialVal, html);\n\n return c.html(html);\n } catch (error) {\n console.error(\"[ui] Error loading docs:\", error);\n\n // Return UI with error message\n const html = await renderIndexPage({\n val: initialVal,\n error: error instanceof Error ? error.message : \"Unknown error\",\n });\n\n return c.html(html);\n }\n}\n",[],[195,466,458],"routes","cccd7cb2-c3e4-11f0-b9d5-42dde27851f2","apiDocs.ts","cccd7d52-c3e4-11f0-b9d5-42dde27851f2",30,["D",1763404790430],"/**\n * API routes for documentation generation\n */\n\nimport type { Context } from \"npm:hono@4.0.0\";\nimport { generateDocs } from \"../services/docService.ts\";\n\n/**\n * GET /api/docs\n * Returns documentation manifest as JSON\n */\nexport async function getApiDocs(c: Context) {\n const val = c.req.query(\"val\");\n\n if (!val) {\n return c.json(\n {\n error: \"BAD_REQUEST\",\n message: 'Missing required query parameter \"val\"',\n example: \"/api/docs?val=username/valname\",\n },\n 400,\n );\n }\n\n try {\n const refresh = c.req.query(\"refresh\") === \"true\";\n const { manifest } = await generateDocs(val, { refresh });\n\n return c.json(manifest);\n } catch (error) {\n console.error(\"[api-docs] Error generating docs:\", error);\n\n if (error instanceof Error) {\n // Handle specific error types\n if (error.message.includes(\"not found\")) {\n return c.json(\n {\n error: \"NOT_FOUND\",\n message: error.message,\n },\n 404,\n );\n }\n\n if (error.message.includes(\"Invalid val identifier\")) {\n return c.json(\n {\n error: \"BAD_REQUEST\",\n message: error.message,\n },\n 400,\n );\n }\n\n return c.json(\n {\n error: \"INTERNAL_ERROR\",\n message: error.message,\n },\n 500,\n );\n }\n\n return c.json(\n {\n error: \"INTERNAL_ERROR\",\n message: \"An unexpected error occurred\",\n },\n 500,\n );\n }\n}\n",[],[195,466,468],"cc622fd4-c3e4-11f0-8120-42dde27851f2",13,["D",1763404789730],[212,213],[195,466],["D",1763404789463],[211,214,219,220],[195],["D",1763401318495],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":54,"_100":101,"_102":24},{"_13":85,"_32":86,"_43":42,"_87":44,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":45,"_94":95},"ctx",{"_78":-5,"_122":520,"_521":522,"_523":524,"_525":24,"_526":24,"_527":24,"_528":58,"_529":-5,"_530":-7,"_531":-7,"_532":62,"_533":24,"_534":24,"_535":-5,"_536":24,"_537":24,"_538":24,"_539":-5},"ENV",{"_491":492,"_493":494,"_495":86,"_496":497,"_498":499,"_500":501,"_502":503,"_504":505,"_506":507,"_508":509,"_510":511,"_512":513,"_514":515,"_516":517,"_518":519},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","71c1b20804b3232a7e513be260cfffc1932a9e97","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 · v59