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`",[],[293],"016036e9-e8a2-48b3-ae74-c5020f917f5e",".vtignore","019f52eb-e63f-75bf-8859-bb7fd6f6ffde",["D",1783802619381],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor",[],[300],"5cb6a8c9-def4-4977-99fb-36f23705feab","docTypes.ts","019f52eb-e63f-75bf-8859-b1072335cea1","019f52eb-e63f-75bf-8859-b68e72d138f4",["D",1783802619381],"/**\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 * Parsed JSDoc-style comment information extracted from TypeScript source.\n */\nexport interface DocComment {\n /** Raw comment text as it appears in source */\n raw: string;\n /** Parsed description text (main comment body) */\n description: string;\n /** Array of @param tag entries */\n params?: Array<{ name: string; type?: string; description: string }>;\n /** @returns tag information */\n returns?: { type?: string; description: string };\n /** Array of @example tag values */\n examples?: string[];\n /** @deprecated tag message, if present */\n deprecated?: string;\n /** Other custom JSDoc tags */\n tags?: Array<{ name: string; value: string }>;\n}\n\n/**\n * Documentation for a function or method parameter.\n */\nexport interface ParameterDoc {\n /** Parameter name */\n name: string;\n /** Type annotation as string */\n type: string;\n /** Whether the parameter is optional */\n optional: boolean;\n /** Default value expression, if present */\n defaultValue?: string;\n /** Description from JSDoc @param tag, if present */\n description?: string;\n}\n\n/**\n * Documentation for a function or arrow function export.\n */\nexport interface FunctionDoc {\n /** Discriminator: always \"function\" */\n kind: \"function\";\n /** Function name */\n name: string;\n /** Full function signature as string */\n signature: string;\n /** Array of parameter documentation */\n parameters: ParameterDoc[];\n /** Return type annotation as string */\n returnType: string;\n /** Whether the function is async */\n isAsync: boolean;\n /** Whether the function is exported */\n isExported: boolean;\n /** JSDoc comment, if present */\n comment?: DocComment;\n /** Source location information */\n location: { line: number; file: string };\n}\n\n/**\n * Documentation for a class property.\n */\nexport interface PropertyDoc {\n /** Property name */\n name: string;\n /** Type annotation as string */\n type: string;\n /** Whether the property is readonly */\n isReadonly: boolean;\n /** Whether the property is optional */\n isOptional: boolean;\n /** Property visibility modifier */\n visibility: \"public\" | \"private\" | \"protected\";\n /** JSDoc comment, if present */\n comment?: DocComment;\n}\n\n/**\n * Documentation for a class method.\n */\nexport interface MethodDoc {\n /** Method name */\n name: string;\n /** Full method signature as string */\n signature: string;\n /** Array of parameter documentation */\n parameters: ParameterDoc[];\n /** Return type annotation as string */\n returnType: string;\n /** Whether the method is async */\n isAsync: boolean;\n /** Whether the method is static */\n isStatic: boolean;\n /** Method visibility modifier */\n visibility: \"public\" | \"private\" | \"protected\";\n /** JSDoc comment, if present */\n comment?: DocComment;\n}\n\n/**\n * Documentation for a class declaration.\n */\nexport interface ClassDoc {\n /** Discriminator: always \"class\" */\n kind: \"class\";\n /** Class name */\n name: string;\n /** Whether the class is exported */\n isExported: boolean;\n /** Whether the class is abstract */\n isAbstract: boolean;\n /** Base class name, if extends clause present */\n extends?: string;\n /** Array of interface names, if implements clause present */\n implements?: string[];\n /** Array of property documentation */\n properties: PropertyDoc[];\n /** Array of method documentation */\n methods: MethodDoc[];\n /** Constructor documentation, if present */\n constructor?: {\n parameters: ParameterDoc[];\n comment?: DocComment;\n };\n /** JSDoc comment, if present */\n comment?: DocComment;\n /** Source location information */\n location: { line: number; file: string };\n}\n\n/**\n * Documentation for an interface property.\n */\nexport interface InterfacePropertyDoc {\n /** Property name */\n name: string;\n /** Type annotation as string */\n type: string;\n /** Whether the property is optional */\n isOptional: boolean;\n /** Whether the property is readonly */\n isReadonly: boolean;\n /** JSDoc comment, if present */\n comment?: DocComment;\n}\n\n/**\n * Documentation for an interface method signature.\n */\nexport interface InterfaceMethodDoc {\n /** Method name */\n name: string;\n /** Full method signature as string */\n signature: string;\n /** Array of parameter documentation */\n parameters: ParameterDoc[];\n /** Return type annotation as string */\n returnType: string;\n /** JSDoc comment, if present */\n comment?: DocComment;\n}\n\n/**\n * Documentation for an interface declaration.\n */\nexport interface InterfaceDoc {\n /** Discriminator: always \"interface\" */\n kind: \"interface\";\n /** Interface name */\n name: string;\n /** Whether the interface is exported */\n isExported: boolean;\n /** Array of extended interface names, if extends clause present */\n extends?: string[];\n /** Array of property documentation */\n properties: InterfacePropertyDoc[];\n /** Array of method documentation */\n methods: InterfaceMethodDoc[];\n /** JSDoc comment, if present */\n comment?: DocComment;\n /** Source location information */\n location: { line: number; file: string };\n}\n\n/**\n * Documentation for a type alias declaration.\n */\nexport interface TypeAliasDoc {\n /** Discriminator: always \"type\" */\n kind: \"type\";\n /** Type alias name */\n name: string;\n /** Type definition as string */\n type: string;\n /** Whether the type alias is exported */\n isExported: boolean;\n /** JSDoc comment, if present */\n comment?: DocComment;\n /** Source location information */\n location: { line: number; file: string };\n}\n\n/**\n * Documentation for a constant or variable declaration.\n */\nexport interface ConstantDoc {\n /** Discriminator: always \"constant\" */\n kind: \"constant\";\n /** Constant name */\n name: string;\n /** Type annotation as string */\n type: string;\n /** Initializer value as string, if present */\n value?: string;\n /** Whether the constant is exported */\n isExported: boolean;\n /** JSDoc comment, if present */\n comment?: DocComment;\n /** Source location information */\n location: { line: number; file: string };\n}\n\n/**\n * Information about an import statement.\n */\nexport interface ImportInfo {\n /** Module source path/URL */\n source: string;\n /** Array of imported items */\n imports: Array<{\n /** Imported name */\n name: string;\n /** Alias name, if imported with `as` */\n alias?: string;\n /** Whether this is a default import */\n isDefault?: boolean;\n /** Whether this is a namespace import (`import * as ...`) */\n isNamespace?: boolean;\n }>;\n /** Source location information */\n location: { line: number; file: string };\n}\n\n/**\n * Val metadata from Val Town API\n */\nexport interface ValMetadata {\n id: string;\n author: { id: string; type: \"user\" | \"org\"; username: string | null };\n createdAt: string;\n description: string | null;\n /**\n * The URL of this val's image\n */\n imageUrl: string | null;\n links: { html: string; self: string };\n name: string;\n /**\n * This resource's privacy setting. Unlisted resources do not appear on profile\n * pages or elsewhere, but you can link to them.\n */\n privacy: \"public\" | \"unlisted\" | \"private\";\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 a value is a valid DocManifest.\n *\n * @param value - Value to check\n * @returns True if value is a DocManifest, false otherwise\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 *\n * @param data - Value to validate\n * @throws Error if value is not a valid 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 with provided metadata.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @param version - Val version identifier\n * @param metadata - Val metadata from Val Town API\n * @returns Empty DocManifest with initialized structure\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",[],[314,307],"shared","f9ad4e5e-7a98-4cc4-b25c-98337160696f",["D",1783802619381],[231],[314],"6803e122-88b4-43e1-a202-fa3d11e9697a","index.tsx","019f52eb-e63f-75bf-8859-a953c230b444","019f52eb-e63f-75bf-8859-afb5df9741d1",["D",1783802619381],"/** @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/**\n * Frontend entry point for the Val Town documentation generator.\n *\n * Retrieves initial data injected by the server and renders the App component.\n */\n\n// Get initial data injected by server\nconst initialData = (window as any).__INITIAL_DATA__ || {};\n\nconst rootElement = document.getElementById(\"root\");\n\nif (!rootElement) {\n\tthrow new Error(\"Failed to find the root element\");\n}\nconst root = createRoot(rootElement);\nroot.render(\n\t\n\t\t\n\t,\n);",[],[327,320],"frontend","c521c1b9-d7d0-40f3-aa5f-a486b7735191","index.html","019f52eb-e63f-75bf-8859-a6558bffb4f5",["D",1783802619381],"\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",[],[327,329],"9080e0f9-6585-40b8-a3b4-d82df713579d","TypeDocCard.tsx","019f52eb-e63f-75bf-8859-9c11b8696ba5","019f52eb-e63f-75bf-8859-a3a1cf8447d7",["D",1783802619381],"/** @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\n/**\n * Props for the TypeDocCard component.\n */\nexport interface TypeDocCardProps {\n /** Type alias documentation to display */\n type: TypeAliasDoc;\n}\n\n/**\n * Component for displaying type alias documentation.\n *\n * Shows type name, definition, and JSDoc comments.\n *\n * @param props - Component props\n * @returns React element\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",[],[327,343,336],"components","9616f59f-39e5-4652-a220-d603a2837f1d","Sidebar.tsx","019f52eb-e63f-75bf-8859-994276e60bb3",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\n\n/**\n * Props for the Sidebar component.\n */\nexport interface SidebarProps {\n /** Documentation manifest to display */\n manifest: DocManifest;\n /** Current search query for filtering */\n searchQuery: string;\n}\n\n/**\n * Sidebar component displaying navigation for all exports in the manifest.\n *\n * Shows val info, and filtered lists of functions, classes, interfaces, types, and constants.\n * Provides click handlers to scroll to each item in the main content.\n *\n * @param props - Component props\n * @returns React element\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 (\n {\n manifest.exports.functions.filter((f) => filterBySearch(f.name))\n .length\n }\n )\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 (\n {\n manifest.exports.classes.filter((c) => filterBySearch(c.name))\n .length\n }\n )\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 (\n {\n manifest.exports.interfaces.filter((i) =>\n filterBySearch(i.name),\n ).length\n }\n )\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 (\n {\n manifest.exports.types.filter((t) => filterBySearch(t.name))\n .length\n }\n )\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 (\n {\n manifest.exports.constants.filter((c) => filterBySearch(c.name))\n .length\n }\n )\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",[],[327,343,345],"b0473541-52ac-4298-be07-c8962475299a","MainContent.tsx","019f52eb-e63f-75bf-8859-95afe00a33dd",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\nimport { ClassDocCard } from \"./ClassDocCard.tsx\";\nimport { ConstantDocCard } from \"./ConstantDocCard.tsx\";\nimport { FunctionDocCard } from \"./FunctionDocCard.tsx\";\nimport { InterfaceDocCard } from \"./InterfaceDocCard.tsx\";\nimport { TypeDocCard } from \"./TypeDocCard.tsx\";\n\n/**\n * Props for the MainContent component.\n */\nexport interface MainContentProps {\n /** Documentation manifest to display */\n manifest: DocManifest;\n /** Current search query for filtering */\n searchQuery: string;\n}\n\n/**\n * Main content area displaying filtered documentation cards.\n *\n * Renders sections for functions, classes, interfaces, types, and constants,\n * filtered by the search query. Shows \"no results\" message when search yields no matches.\n *\n * @param props - Component props\n * @returns React element\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

\n {manifest.metadata.readme}\n

\n )}\n

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

\n No results found for \"{searchQuery}\"\n

\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

\n Interfaces\n

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

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

\n Type Aliases\n

\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",[],[327,343,352],"5e4f7690-3a08-4e89-892e-4623e9e1e4b0","LoadingSpinner.tsx","019f52eb-e63f-75bf-8859-93844c2fb3ce",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\n/**\n * Component for displaying a loading spinner with message.\n *\n * @returns React element\n */\nexport function LoadingSpinner() {\n return (\n

Generating documentation...

\n );\n}\n",[],[327,343,359],"7b742f6e-693f-444c-bc85-8c1dbbb19f8c","InterfaceDocCard.tsx","019f52eb-e63f-75bf-8859-8fb41fe22050",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { InterfaceDoc } from \"../../shared/docTypes.ts\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\n/**\n * Props for the InterfaceDocCard component.\n */\nexport interface InterfaceDocCardProps {\n /** Interface documentation to display */\n iface: InterfaceDoc;\n}\n\n/**\n * Component for displaying interface documentation.\n *\n * Shows interface name, extends clauses, properties, methods, and JSDoc comments.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function InterfaceDocCard(props: InterfaceDocCardProps) {\n const { iface } = props;\n\n return (\n \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

\n Properties\n

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

\n \n {prop.isReadonly && (\n readonly \n )}\n {prop.name}\n {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",[],[327,343,366],"478f12dc-c162-4a28-83d4-362f8489a709","Header.tsx","019f52eb-e63f-75bf-8859-88ab95bfcc11",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type React from \"https://esm.sh/react@18.2.0\";\nimport { useState } from \"https://esm.sh/react@18.2.0\";\n\n/**\n * Props for the Header component.\n */\nexport interface HeaderProps {\n /** Callback when val form is submitted */\n onSubmit: (val: string) => void;\n /** Callback when refresh button is clicked */\n onRefresh: () => void;\n /** Currently displayed val identifier */\n currentVal: string;\n /** Callback when search query changes */\n onSearchChange: (query: string) => void;\n}\n\n/**\n * Header component with val input form, refresh button, and search input.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function Header(props: HeaderProps): React.ReactElement {\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",[],[327,343,373],"cb3f5470-5333-40c5-a749-d493354c03f1","FunctionDocCard.tsx","019f52eb-e63f-75bf-8859-84005b7ed1e1",["D",1783802619381],"/** @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\n/**\n * Props for the FunctionDocCard component.\n */\nexport interface FunctionDocCardProps {\n /** Function documentation to display */\n func: FunctionDoc;\n}\n\n/**\n * Component for displaying function documentation.\n *\n * Shows function name, signature, parameters, return type, and JSDoc comments.\n *\n * @param props - Component props\n * @returns React element\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

\n Parameters\n

\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
\n {param.name}\n	{param.type}	{param.optional ? \"Yes\" : \"No\"}	\n {param.defaultValue \|\| \"-\"}\n

\n )}\n\n

Returns

\n \n {func.returnType}\n \n

\n );\n}\n",[],[327,343,380],"f3fc4acb-c6f6-45bd-9335-53068ff1c359","ErrorMessage.tsx","019f52eb-e63f-75bf-8859-835160450231",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\n/**\n * Props for the ErrorMessage component.\n */\nexport interface ErrorMessageProps {\n /** Error message to display */\n message: string;\n}\n\n/**\n * Component for displaying error messages with styling.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function ErrorMessage(props: ErrorMessageProps) {\n return (\n

\n ❌\n

Error

{props.message}

\n );\n}\n",[],[327,343,387],"2e9ccd37-97e6-410e-b00f-522c63b32a53","DocCommentDisplay.tsx","019f52eb-e63f-75bf-8859-7cfc16a8584c",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { DocComment } from \"../../shared/docTypes.ts\";\n\n/**\n * Props for the DocCommentDisplay component.\n */\nexport interface DocCommentDisplayProps {\n /** Documentation comment to display */\n comment: DocComment;\n}\n\n/**\n * Component for displaying parsed JSDoc comments.\n *\n * Renders description, @param tags, @returns tag, @example tags, and @deprecated warnings.\n *\n * @param props - Component props\n * @returns React element\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 \n ({param.type})\n \n )}\n {param.description && (\n \n {param.description}\n \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",[],[327,343,394],"5ec0ce10-4990-4dd5-9411-39a6dceca759","ConstantDocCard.tsx","019f52eb-e63f-75bf-8859-78a7aa52f6db",["D",1783802619381],"/** @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\n/**\n * Props for the ConstantDocCard component.\n */\nexport interface ConstantDocCardProps {\n /** Constant documentation to display */\n constant: ConstantDoc;\n}\n\n/**\n * Component for displaying constant/variable documentation.\n *\n * Shows constant name, type, value, and JSDoc comments.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function ConstantDocCard(props: ConstantDocCardProps) {\n const { constant } = props;\n\n return (\n \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 \n {constant.type}\n \n

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

Value

\n \n

\n )}\n \n );\n}\n",[],[327,343,401],"ac2138bf-42eb-4929-91da-eec598683dc4","CodeBlock.tsx","019f52eb-e63f-75bf-8859-764e95e42ee8",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\n/**\n * Props for the CodeBlock component.\n */\nexport interface CodeBlockProps {\n /** Code content to display */\n code: string;\n /** Language identifier for syntax highlighting (currently unused) */\n language?: string;\n}\n\n/**\n * Component for displaying code blocks with syntax formatting.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function CodeBlock(props: CodeBlockProps) {\n return (\n

\n      {props.code}\n

\n );\n}\n",[],[327,343,408],"a6469d09-6b10-43e4-98c5-87a7474f37c6","ClassDocCard.tsx","019f52eb-e63f-75bf-8859-737299ddaf3b",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type { ClassDoc } from \"../../shared/docTypes.ts\";\nimport { DocCommentDisplay } from \"./DocCommentDisplay.tsx\";\n\n/**\n * Props for the ClassDocCard component.\n */\nexport interface ClassDocCardProps {\n /** Class documentation to display */\n cls: ClassDoc;\n}\n\n/**\n * Component for displaying class documentation.\n *\n * Shows class name, extends/implements clauses, constructor, properties, methods, and JSDoc comments.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function ClassDocCard(props: ClassDocCardProps) {\n const { cls } = props;\n\n return (\n

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

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

\n extends{\" \"}\n {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

\n Constructor\n

\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
\n {param.name}\n	\n {param.type}\n

\n )}\n

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

\n Properties\n

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

\n \n {prop.visibility !== \"public\" && (\n {prop.visibility} \n )}\n {prop.isReadonly && (\n readonly \n )}\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 && (\n static \n )}\n {method.isAsync && (\n async \n )}\n {method.name}()\n

\n {method.comment && (\n

\n {method.comment.description}\n

\n )}\n

\n ))}\n

\n )}\n

\n );\n}\n",[],[327,343,415],"d6577708-da8b-4ac1-89cc-ff0cc6f70e84","App.tsx","019f52eb-e63f-75bf-8859-6d528a04baef",["D",1783802619381],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport type React from \"https://esm.sh/react@18.2.0\";\nimport { useState } from \"https://esm.sh/react@18.2.0\";\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\nimport { ErrorMessage } from \"./ErrorMessage.tsx\";\nimport { Header } from \"./Header.tsx\";\nimport { LoadingSpinner } from \"./LoadingSpinner.tsx\";\nimport { MainContent } from \"./MainContent.tsx\";\nimport { Sidebar } from \"./Sidebar.tsx\";\n\n/**\n * Props for the main App component.\n */\nexport interface AppProps {\n /** Initial documentation manifest (from SSR) */\n initialManifest?: DocManifest;\n /** Initial val identifier */\n initialVal?: string;\n /** Initial error message */\n error?: string;\n}\n\n/**\n * Main application component for the Val Town documentation generator.\n *\n * Manages state for documentation manifest, loading states, errors, and search.\n * Handles fetching documentation from the API and rendering the UI.\n *\n * @param props - Component props\n * @returns React element\n */\nexport function App(props: AppProps): React.ReactElement {\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(\n `[fetchDocs] Requesting docs for val: ${valIdentifier}, refresh: ${refresh}`,\n );\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(\n `[fetchDocs] Response status: ${response.status} ${response.statusText}`,\n );\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 globalThis.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 \n Automatic extraction of functions, classes, interfaces, types,\n and constants\n \n
\n 💬\n \n JSDoc comment parsing with @param, @returns, and @example tags\n \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",[],[327,343,422],"4edd4a0a-e005-42e9-a6f5-ebc5a139a923",["D",1783802619381],[215,216,217,218,219,220,221,222,223,224,225,226,227],[327,343],"f2857290-2d34-43a0-acdb-f7b4860f4e65",["D",1783802619381],[214,228,229],[327],["D",1783802619381],[],[18,75],"be58b0f1-d0c4-4883-89f3-6ba3cb5a693c","valFetcher.ts","019f52eb-e63f-75bf-8859-5deba9e6f5a2",["D",1783802619381],"/**\n * Val Town API client for fetching val metadata and source code\n * Uses the official @valtown/sdk for API interactions\n */\n``;\n\nimport ValTown from \"npm:@valtown/sdk@latest\";\nimport type { ValMetadata } from \"../../shared/docTypes.ts\";\n\n// type Val\n\n/**\n * Represents a file in a val bundle\n */\nexport interface ValFile {\n /** File path relative to val root */\n path: string;\n /** File content as string */\n content: string;\n}\n\n/**\n * Complete val bundle with metadata and source files.\n */\nexport interface ValBundle {\n /** Val version identifier */\n version: string;\n /** Val metadata from Val Town API */\n metadata: ValMetadata;\n /** Array of source files in the val */\n files: ValFile[];\n}\n\n/**\n * Parses a val identifier string into username and val name components.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @returns Object with username and valname properties\n * @throws Error if val identifier format is invalid\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 * Fetches val metadata using the official Val Town SDK.\n *\n * @param client - Val Town SDK client instance\n * @param username - Username of the val owner\n * @param valname - Name of the val\n * @returns Val metadata object\n * @throws Error if val is not found or fetch fails\n */\nexport async 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 return {\n id: val.id,\n name: val.name,\n author: {\n username: val.author?.username || username,\n id: val.author?.id || \"\",\n type: val.author?.type || \"user\",\n },\n links: {\n html: val.links.html,\n self: val.links.self,\n },\n description: val.description || \"\",\n imageUrl: val.imageUrl || \"\",\n privacy: val.privacy || \"public\",\n createdAt: val.createdAt || \"\",\n };\n } catch (error) {\n if (error instanceof ValTown.NotFoundError) {\n throw new Error(`Val not found: ${username}/${valname}`);\n }\n throw new Error(`Failed to fetch val metadata: ${error.message}`);\n }\n}\n\n/**\n * Retrieves the list of file paths in a val.\n *\n * @param client - Val Town SDK client instance\n * @param valMetadata - Val metadata containing the val ID\n * @returns Array of file paths\n */\nasync function getValFiles(\n client: ValTown,\n valMetadata: ValMetadata,\n): Promise {\n const files = [];\n for await (const file of client.vals.files.retrieve(valMetadata.id, {\n limit: 1,\n offset: 0,\n path: \"\",\n recursive: true,\n })) {\n if (file.type !== \"directory\") {\n files.push(file.path);\n }\n }\n return files;\n}\n\n/**\n * Fetches the source code content for a specific file in a val.\n *\n * @param client - Val Town SDK client instance\n * @param valId - Val ID\n * @param filePath - Path to the file within the val\n * @returns File content as string\n * @throws Error if file fetch fails\n */\nasync function fetchFileSource(\n client: ValTown,\n valId: string,\n filePath: string,\n): Promise {\n try {\n const response = await client.vals.files.getContent(valId, {\n path: filePath,\n });\n\n return await response.text();\n } catch (error) {\n throw new Error(`Failed to fetch val source: ${error.message}`);\n }\n}\n\n/**\n * Interface for fetching val bundles from Val Town.\n */\nexport interface ValFetcher {\n /**\n * Fetches the latest version of a val bundle.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @returns Complete val bundle with metadata and files\n */\n fetchLatest(val: string): Promise;\n}\n\n/**\n * Creates a Val Town API fetcher instance using the official SDK.\n *\n * @returns Configured ValFetcher instance\n */\nexport function createValFetcher(): ValFetcher {\n const client = new ValTown();\n\n return {\n async fetchLatest(val: string): Promise {\n const { username, valname } = parseValIdentifier(val);\n const metadata = await fetchValMetadata(client, username, valname);\n const fileList = await getValFiles(client, metadata);\n const files: ValFile[] = [];\n\n for (const filePath of fileList) {\n const content = await fetchFileSource(client, metadata.id, filePath);\n files.push({\n path: filePath,\n content,\n });\n }\n\n return {\n metadata,\n files,\n version: new Date().toISOString(),\n };\n },\n };\n}\n\n/**\n * Default val fetcher instance for use throughout the application.\n */\nexport const valFetcher = createValFetcher();\n",[],[18,87,440],"28fbcca0-4870-494c-bdf3-5e476da5d1ae","tsParser.ts","019f52eb-e63f-75bf-8859-583526e205da",["D",1783802619381],"/**\n * TypeScript AST parser for extracting documentation\n * Uses the TypeScript Compiler API to walk the AST and extract exports\n */\n\nimport 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} from \"../../shared/docTypes.ts\";\nimport { createEmptyManifest } from \"../../shared/docTypes.ts\";\nimport type { ValBundle } from \"./valFetcher.ts\";\n\n/**\n * Parses JSDoc comment from a TypeScript AST node.\n *\n * Extracts description, @param tags, @returns tag, @example tags, and @deprecated tag.\n *\n * @param node - The TypeScript AST node to extract comments from\n * @param sourceFile - The source file containing the node\n * @returns Parsed documentation comment, or undefined if no comment exists\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 paramTag = tag as ts.JSDocParameterTag;\n const name = paramTag.name ? paramTag.name.getText(sourceFile) : \"\";\n const desc =\n typeof tag.comment === \"string\"\n ? tag.comment\n : tag.comment\n ? tag.comment.map((part) => part.text).join(\"\")\n : \"\";\n console.log(`[tsParser] ${desc}`);\n return {\n name,\n type: undefined,\n description: desc.trim().replace(/^[-–—]\\s*/, \"\"), // Remove leading dash/hyphen\n };\n });\n }\n\n // Parse @returns tag\n const returnTag = jsDocTags.find((tag) => tag.tagName.text === \"returns\");\n if (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(\n (tag) => 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 * Converts a TypeScript type node to its string representation.\n *\n * @param typeNode - The type node to convert, or undefined\n * @param _checker - Type checker (unused, kept for API consistency)\n * @param sourceFile - The source file containing the type node\n * @returns String representation of the type, or \"any\" if undefined\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 * Parses function or method parameters from TypeScript AST.\n *\n * Extracts parameter name, type, optional status, and default value.\n *\n * @param parameters - Array of parameter declaration nodes\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the parameters\n * @returns Array of parsed 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 * Parses a function declaration or arrow function expression.\n *\n * Handles both `function foo()` and `export const foo = () => {}` patterns.\n *\n * @param node - Function declaration or variable statement node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the function\n * @returns Parsed function documentation, or null if node is not a function\n */\nfunction parseFunctionDeclaration(\n node: ts.FunctionDeclaration | ts.VariableStatement,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): FunctionDoc | null {\n let funcDecl:\n | ts.FunctionDeclaration\n | ts.ArrowFunction\n | 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(\n (m) => m.kind === ts.SyntaxKind.ExportKeyword,\n );\n } else if (ts.isVariableStatement(node)) {\n // Handle: export const foo = () => {}\n isExported = !!node.modifiers?.some(\n (m) => 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(funcDecl.parameters, checker, sourceFile);\n const returnType = getTypeString(funcDecl.type, checker, sourceFile);\n const isAsync = !!funcDecl.modifiers?.some(\n (m) => m.kind === ts.SyntaxKind.AsyncKeyword,\n );\n const comment = parseJSDocComment(node, sourceFile);\n const line =\n sourceFile.getLineAndCharacterOfPosition(node.getStart()).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 * Parses a class property declaration.\n *\n * Extracts property name, type, readonly status, optional status, visibility, and documentation.\n *\n * @param node - Property declaration node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the property\n * @returns Parsed property documentation\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(\n (m) => 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 * Parses a class method declaration.\n *\n * Extracts method name, signature, parameters, return type, async status, static status, visibility, and documentation.\n *\n * @param node - Method declaration node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the method\n * @returns Parsed method documentation\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(\n (m) => m.kind === ts.SyntaxKind.AsyncKeyword,\n );\n const isStatic = !!node.modifiers?.some(\n (m) => 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 * Parses a class declaration.\n *\n * Extracts class name, export status, abstract status, extends/implements clauses,\n * properties, methods, constructor, and documentation.\n *\n * @param node - Class declaration node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the class\n * @returns Parsed class documentation, or null if class has no name\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(\n (m) => m.kind === ts.SyntaxKind.ExportKeyword,\n );\n const isAbstract = !!node.modifiers?.some(\n (m) => m.kind === ts.SyntaxKind.AbstractKeyword,\n );\n\n const extendsClause = node.heritageClauses?.find(\n (c) => c.token === ts.SyntaxKind.ExtendsKeyword,\n );\n const extendsType = extendsClause?.types[0]?.getText(sourceFile);\n\n const implementsClause = node.heritageClauses?.find(\n (c) => 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 // biome-ignore lint/suspicious/noShadowRestrictedNames: constructor is a reserved word\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 =\n sourceFile.getLineAndCharacterOfPosition(node.getStart()).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 * Parses an interface property signature.\n *\n * Extracts property name, type, optional status, readonly status, and documentation.\n *\n * @param node - Property signature node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the property\n * @returns Parsed interface property documentation\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(\n (m) => 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 * Parses an interface method signature.\n *\n * Extracts method name, signature, parameters, return type, and documentation.\n *\n * @param node - Method signature node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the method\n * @returns Parsed interface method documentation\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 * Parses an interface declaration.\n *\n * Extracts interface name, export status, extends clauses, properties, methods, and documentation.\n *\n * @param node - Interface declaration node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the interface\n * @returns Parsed interface documentation\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(\n (m) => 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 =\n sourceFile.getLineAndCharacterOfPosition(node.getStart()).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 * Parses a type alias declaration.\n *\n * Extracts type name, type definition, export status, and documentation.\n *\n * @param node - Type alias declaration node\n * @param _checker - Type checker (unused, kept for API consistency)\n * @param sourceFile - The source file containing the type alias\n * @returns Parsed type alias documentation\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(\n (m) => m.kind === ts.SyntaxKind.ExportKeyword,\n );\n const comment = parseJSDocComment(node, sourceFile);\n const line =\n sourceFile.getLineAndCharacterOfPosition(node.getStart()).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 * Parses a constant or variable declaration.\n *\n * Skips function declarations (arrow functions and function expressions) as they are handled separately.\n *\n * @param node - Variable statement node\n * @param checker - TypeScript type checker\n * @param sourceFile - The source file containing the constant\n * @returns Parsed constant documentation, or null if node is a function or has no 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(checker.getTypeAtLocation(declaration));\n const value = declaration.initializer?.getText(sourceFile);\n const isExported = !!node.modifiers?.some(\n (m) => m.kind === ts.SyntaxKind.ExportKeyword,\n );\n const comment = parseJSDocComment(node, sourceFile);\n const line =\n sourceFile.getLineAndCharacterOfPosition(node.getStart()).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 * Parses an import declaration.\n *\n * Handles default imports, named imports, namespace imports, and aliases.\n *\n * @param node - Import declaration node\n * @param sourceFile - The source file containing the import\n * @returns Parsed import information\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 =\n sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1;\n\n return {\n source,\n imports,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parses a Val bundle and extracts comprehensive documentation.\n *\n * Creates a TypeScript compiler program from the bundle's files, walks the AST,\n * and extracts all exports (functions, classes, interfaces, types, constants) along\n * with their documentation comments and metadata.\n *\n * @param bundle - The Val bundle containing metadata and source files\n * @returns Complete documentation manifest with all parsed exports\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: 6, // ES2020\n module: 99, // 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 6, // 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",[],[18,87,447],"a19b905b-edb7-4305-b0c1-eb299a0543c6","docService.ts","019f52eb-e63f-75bf-8859-56dd233910b8",["D",1783802619381],"/**\n * Documentation generation service\n * Orchestrates fetching, parsing, and caching of val documentation\n */\n\nimport type { DocManifest } from \"../../shared/docTypes.ts\";\nimport { deriveCacheKey, docCache } from \"./docCache.ts\";\nimport { parseValBundle } from \"./tsParser.ts\";\nimport { valFetcher } from \"./valFetcher.ts\";\n\n/**\n * Cached documentation payload containing manifest and optional SSR HTML.\n */\nexport interface CachedDocPayload {\n /** The documentation manifest */\n manifest: DocManifest;\n /** Server-side rendered HTML (optional, cached for performance) */\n ssrHtml?: string;\n /** Timestamp when the payload was cached (milliseconds since epoch) */\n cachedAt: number;\n}\n\n/**\n * Options for documentation generation.\n */\nexport interface GenerateDocsOptions {\n /** If true, bypasses cache and regenerates documentation */\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 * Forces a refresh of documentation for a val, bypassing cache.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @returns Freshly generated documentation payload\n */\nexport async function refreshDocs(val: string): Promise {\n return generateDocs(val, { refresh: true });\n}\n\n/**\n * Retrieves cached documentation without generating new documentation.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @returns Cached documentation payload if available, null otherwise\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 * Updates the SSR HTML in the cached documentation payload.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @param html - The HTML string to 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 * Clears the documentation cache for a specific val.\n *\n * @param val - Val identifier in format \"username/valname\"\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 * Clears all documentation caches.\n *\n * Removes all cached documentation from both memory and blob storage.\n */\nexport async function clearAllCaches(): Promise {\n await docCache.clear();\n console.log(\"[doc-service] Cleared all documentation caches\");\n}\n",[],[18,87,454],"aaf0104c-53ba-4ece-8e26-b3e7f7262b4c","docCache.ts","019f52eb-e63f-75bf-8859-518c209954aa",["D",1783802619381],"/**\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 with metadata for expiration and versioning.\n *\n * @template T - Type of cached data\n */\nexport interface CacheEntry {\n /** Cached data */\n data: T;\n /** Version identifier for cache invalidation */\n version: string;\n /** Timestamp when entry was cached (milliseconds since epoch) */\n cachedAt: number;\n /** Timestamp when entry expires (milliseconds since epoch) */\n expiresAt: number;\n}\n\n/**\n * Configuration options for documentation cache.\n */\nexport interface CacheConfig {\n /** Cache time-to-live in milliseconds (default: 1 hour) */\n ttlMs?: number;\n /** Prefix for blob storage keys (default: \"doc-cache\") */\n blobPrefix?: string;\n}\n\n/**\n * Interface for documentation cache operations.\n *\n * Provides a two-tier caching system: in-memory LRU cache with blob storage fallback.\n */\nexport interface DocCache {\n /**\n * Retrieves cached data by key.\n *\n * @template T - Type of cached data\n * @param key - Cache key\n * @returns Cached data if found and not expired, null otherwise\n */\n get(key: string): Promise;\n /**\n * Stores data in cache with version metadata.\n *\n * @template T - Type of data to cache\n * @param key - Cache key\n * @param data - Data to cache\n * @param metadata - Cache metadata including version\n */\n set(key: string, data: T, metadata: { version: string }): Promise;\n /**\n * Checks if a key exists in cache and is not expired.\n *\n * @param key - Cache key\n * @returns True if key exists and is valid, false otherwise\n */\n has(key: string): Promise;\n /**\n * Checks if a cache entry is expired.\n *\n * @param key - Cache key\n * @returns True if expired or doesn't exist, false if valid\n */\n isExpired(key: string): Promise;\n /**\n * Deletes a cache entry by key.\n *\n * @param key - Cache key\n */\n delete(key: string): Promise;\n /**\n * Clears all cache entries.\n */\n clear(): Promise;\n}\n\n/**\n * In-memory cache with LRU (Least Recently Used) eviction policy.\n *\n * Maintains a fixed-size cache, automatically evicting the oldest entry when at capacity.\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 * Creates a documentation cache instance with two-tier storage.\n *\n * Uses in-memory LRU cache for fast access and blob storage for persistence.\n *\n * @param config - Cache configuration options\n * @returns Configured DocCache 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(\n blobKey,\n )) as CacheEntry | 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 * Derives a normalized cache key from a val identifier and optional version.\n *\n * Normalizes the val identifier by lowercasing and replacing invalid characters.\n *\n * @param val - Val identifier in format \"username/valname\"\n * @param version - Optional version string to append\n * @returns Normalized cache key\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 documentation cache instance with 1 hour TTL.\n *\n * Uses \"doc-manifest\" as the blob storage prefix.\n */\nexport const docCache = createDocCache({\n ttlMs: 60 * 60 * 1000,\n blobPrefix: \"doc-manifest\",\n});\n",[],[18,87,461],["D",1783802619381],[208,209,210,211],[18,87],"97a2a13b-d2cb-4c97-b044-57785544440c","ui.ts","019f52eb-e63f-75bf-8859-49221c3e62f5",["D",1783802619381],"/**\n * UI routes for serving the documentation viewer\n */\n\nimport { readFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport type { Context } from \"npm:hono@4.0.0\";\nimport { generateDocs, updateCachedHtml } from \"../services/docService.ts\";\n\n/**\n * Renders the HTML index page with optional initial data injected.\n *\n * Injects data into a script tag to avoid extra round-trips on initial page load.\n *\n * @param data - Initial data to inject (manifest, val identifier, or error)\n * @returns HTML string with injected 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 *\n * Serves the documentation viewer UI.\n *\n * Query parameters:\n * - `val` (optional): Val identifier in format \"username/valname\"\n *\n * If a val is specified, attempts to load cached documentation and inject it\n * into the page. Falls back to empty UI if no val is provided.\n *\n * @param c - Hono context object\n * @returns HTML response with 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",[],[18,93,471],"ec322dd8-70b4-4869-b0df-c1417b4ea02c","apiDocs.ts","019f52eb-e63f-75bf-8859-46c6ef1983be",["D",1783802619381],"/**\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 *\n * Returns documentation manifest as JSON for a given val.\n *\n * Query parameters:\n * - `val` (required): Val identifier in format \"username/valname\"\n * - `refresh` (optional): Set to \"true\" to bypass cache and regenerate docs\n *\n * @param c - Hono context object\n * @returns JSON response with documentation manifest or error details\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",[],[18,93,478],["D",1783802619381],[205,206],[18,93],["D",1783802619381],[204,207,212],[18],["D",1783802619381],{"_11":12,"_143":81},{"_11":12,"_139":-5,"_80":81,"_31":79,"_140":141,"_142":30},{"_39":40,"_13":16,"_33":36,"_129":96,"_130":70,"_131":132,"_133":100,"_134":135,"_136":42,"_137":14,"_138":12},"ctx",{"_52":-5,"_164":527,"_528":529,"_530":531,"_532":30,"_533":30,"_534":30,"_535":24,"_536":-5,"_537":-7,"_538":-7,"_539":26,"_540":30,"_541":30,"_542":-5,"_543":30,"_544":30,"_545":30,"_546":-5},"ENV",{"_498":499,"_500":501,"_502":16,"_503":504,"_505":506,"_507":508,"_509":510,"_511":512,"_513":514,"_515":516,"_517":518,"_519":520,"_521":522,"_523":524,"_525":526},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","899124c68db8496248a17ee95f074b807335ea7b","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"]

History · backend