[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_495":496,"_497":498},"routes/_app.x.$handle.$name",{"_98":97,"_32":46,"_106":88,"_27":54,"_13":14,"_107":-5,"_11":108,"_109":110,"_111":112,"_113":114,"_115":116,"_20":-5,"_117":-5,"_118":-5,"_119":25,"_120":121,"_122":60,"_123":-5,"_124":-5,"_125":126},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_44":45,"_32":46,"_39":47,"_48":-5,"_49":25,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":58,"_59":60,"_61":60,"_62":-5,"_63":64,"_65":66,"_67":-5,"_68":-5,"_69":-5,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":81,"_82":83,"_84":85,"_86":25},"version",149,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":35,"_36":38,"_39":40,"_41":14,"_42":43,"_24":25},"previous",{"_30":31,"_32":33,"_34":35,"_36":37},"deleted",false,"deletedHere","path","backend/services/valFetcher.ts","latestPath","fileId","ccdc741a-c3e4-11f0-b1eb-42dde27851f2","name","valFetcher.ts","fileType","script","content","/**\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\tpath: string;\n\tcontent: string;\n}\n\n/**\n * Complete val bundle with metadata and source files\n */\nexport interface ValBundle {\n\tmetadata: ValMetadata;\n\tfiles: ValFile[];\n}\n\n/**\n * Parse val identifier into username and val name\n */\nexport function parseValIdentifier(val: string): {\n\tusername: string;\n\tvalname: string;\n} {\n\tconst parts = val.split(\"/\");\n\tif (parts.length !== 2) {\n\t\tthrow new Error(\n\t\t\t`Invalid val identifier \"${val}\". Expected format: username/valname`,\n\t\t);\n\t}\n\treturn { username: parts[0], valname: parts[1] };\n}\n\n/**\n * Fetch val metadata using the official Val Town SDK\n */\nexport async function fetchValMetadata(\n\tclient: ValTown,\n\tusername: string,\n\tvalname: string,\n): Promise {\n\ttry {\n\t\t// Use the SDK's alias retrieve method to fetch val metadata\n\t\tconsole.log(\n\t\t\t`[valFetchr] calling client.alias.username.valName.retrieve(${valname}, {\n username: ${username}`,\n\t\t);\n\t\tconst val = await client.alias.username.valName.retrieve(valname, {\n\t\t\tusername,\n\t\t});\n\n\t\t// id: string;\n\t\t// author: Val.Author;\n\t\t// createdAt: string;\n\t\t// description: string | null;\n\t\t// /**\n\t\t// * The URL of this val's image\n\t\t// */\n\t\t// imageUrl: string | null;\n\t\t// links: Val.Links;\n\t\t// name: string;\n\t\t// /**\n\t\t// * This resource's privacy setting. Unlisted resources do not appear on profile\n\t\t// * pages or elsewhere, but you can link to them.\n\t\t// */\n\t\t// privacy: \"public\" | \"unlisted\" | \"private\";\n\t\t// Map SDK response to our ValMetadata format\n\t\treturn {\n\t\t\tid: val.id,\n\t\t\tname: val.name,\n\t\t\tauthor: {\n\t\t\t\tusername: val.author?.username || username,\n\t\t\t\tid: val.author?.id || \"\",\n\t\t\t\ttype: val.author?.type || \"user\",\n\t\t\t},\n\t\t\tlinks: {\n\t\t\t\thtml: val.links.html,\n\t\t\t\tself: val.links.self,\n\t\t\t},\n\t\t\tdescription: val.description || \"\",\n\t\t\timageUrl: val.imageUrl || \"\",\n\t\t\tprivacy: val.privacy || \"public\",\n\t\t\tcreatedAt: val.createdAt || \"\",\n\t\t};\n\t} catch (error) {\n\t\tif (error instanceof ValTown.NotFoundError) {\n\t\t\tthrow new Error(`Val not found: ${username}/${valname}`);\n\t\t}\n\t\tthrow new Error(`Failed to fetch val metadata: ${error.message}`);\n\t}\n}\n\nasync function getValFiles(\n\tclient: ValTown,\n\tvalMetadata: ValMetadata,\n): Promise {\n\tconst files = [];\n\tfor await (const file of client.vals.files.retrieve(valMetadata.id, {\n\t\tlimit: 1,\n\t\toffset: 0,\n\t\tpath: \"\",\n\t\trecursive: true,\n\t})) {\n\t\tif (file.type !== \"directory\") {\n\t\t\tfiles.push(file.path);\n\t\t}\n\t}\n\treturn files;\n}\n\n/**\n * Fetch the source code for a given file\n */\nasync function fetchFileSource(\n\tclient: ValTown,\n\tvalId: string,\n\tfilePath: string,\n): Promise {\n\ttry {\n\t\tconst response = await client.vals.files.getContent(valId, {\n\t\t\tpath: filePath,\n\t\t});\n\n\t\treturn await response.text();\n\t} catch (error) {\n\t\tthrow new Error(`Failed to fetch val source: ${error.message}`);\n\t}\n}\n\n/**\n * Main Val fetcher interface\n */\nexport interface ValFetcher {\n\tfetchLatest(val: string): Promise;\n}\n\n/**\n * Create a Val Town API fetcher using the official SDK\n */\nexport function createValFetcher(): ValFetcher {\n\tconst client = new ValTown();\n\n\treturn {\n\t\tasync fetchLatest(val: string): Promise {\n\t\t\tconst { username, valname } = parseValIdentifier(val);\n\t\t\tconst metadata = await fetchValMetadata(client, username, valname);\n\t\t\tconst fileList = await getValFiles(client, metadata);\n\t\t\tconst files: ValFile[] = [];\n\n\t\t\tfor (const filePath of fileList) {\n\t\t\t\tconst content = await fetchFileSource(client, metadata.id, filePath);\n\t\t\t\tfiles.push({\n\t\t\t\t\tpath: filePath,\n\t\t\t\t\tcontent,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\tmetadata,\n\t\t\t\tfiles,\n\t\t\t};\n\t\t},\n\t};\n}\n\n/**\n * Default val fetcher instance\n */\nexport const valFetcher = createValFetcher();\n","/**\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","createdAt",["D",1763426599430],"branchVersion","branchId","b75c761a-c3dc-11f0-a370-42dde27851f2","id","b75c3768-c3dc-11f0-a370-42dde27851f2","docs-gen",["D",1763401318495],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","ccc2b142-c3e4-11f0-b160-42dde27851f2","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_98":97,"_105":101},"org",{"_98":97,"_99":-5,"_100":101,"_18":56,"_102":103,"_104":25},"branch",{"_13":87,"_32":88,"_44":43,"_89":45,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":46,"_96":97},"isOwned",181,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_44":45,"_32":46,"_39":491,"_48":-5,"_49":25,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":58,"_59":60,"_61":60,"_62":-5,"_63":64,"_65":66,"_67":-5,"_68":-5,"_69":-5,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":492,"_82":493,"_84":494,"_86":25},"tree",[220,230,247,249,250,251,252,253,254,255],"files",[220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255],"counts",{"_210":64,"_211":144,"_212":144,"_213":214,"_215":216},"contents",[127,128,129,130,131,132,133,134,135,136],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_44":204,"_32":205,"_30":206,"_140":-5,"_42":43,"_41":207,"_142":60,"_39":208,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_27":209},{"_44":198,"_32":199,"_30":200,"_140":-5,"_42":43,"_41":201,"_142":60,"_39":202,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_27":203},{"_44":191,"_32":192,"_30":193,"_140":-5,"_42":43,"_41":194,"_142":60,"_39":195,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_27":197},{"_44":185,"_32":186,"_30":187,"_140":-5,"_42":43,"_41":161,"_142":60,"_39":188,"_13":64,"_34":20,"_36":189,"_24":25,"_146":-5,"_27":190},{"_44":178,"_32":179,"_30":180,"_140":-5,"_42":43,"_41":181,"_142":60,"_39":182,"_13":64,"_34":20,"_36":183,"_24":25,"_146":-5,"_27":184},{"_44":171,"_32":172,"_30":173,"_140":-5,"_42":43,"_41":174,"_142":25,"_39":175,"_13":144,"_34":20,"_36":176,"_24":25,"_146":-5,"_27":177},{"_44":164,"_32":165,"_30":166,"_140":-5,"_42":43,"_41":167,"_142":25,"_39":168,"_13":144,"_34":20,"_36":169,"_24":25,"_146":-5,"_27":170},{"_44":156,"_32":157,"_30":158,"_140":-5,"_42":43,"_41":159,"_142":60,"_39":160,"_13":161,"_34":20,"_36":162,"_24":25,"_146":-5,"_27":163},{"_44":148,"_32":149,"_30":150,"_140":-5,"_42":43,"_41":151,"_142":25,"_39":152,"_13":153,"_34":35,"_36":154,"_24":25,"_146":-5,"_27":155},{"_44":137,"_32":138,"_30":139,"_140":-5,"_42":43,"_41":141,"_142":60,"_39":143,"_13":144,"_34":20,"_36":145,"_24":25,"_146":-5,"_27":147},"2e7fb8d0-c3e0-11f0-beda-42dde27851f2","valtown-docs-generator-plan.md","d793abce-c3dc-11f0-b5a6-42dde27851f2","parentId",8,"latest",["D",1763402806837],1,"# Implementation Plan\n\n## Goal\n\n- After completion, visiting the published `docGenerator` HTTP val with a `?val=username/valname` query returns generated API docs < 3s for a representative public val.\n- Success criteria:\n - `GET /api/docs?val=acme/sample` responds 200 with parsed exports (functions, types, constants) in JSON validated against `DocManifest` schema.\n - UI route `/` renders documentation cards for the same sample val with syntax highlighting and navigation.\n - Cache hits logged for repeat requests within 1 hour, cache misses stay under 2 API calls per request and serve cached manifests/HTML within ~20 ms.\n- Scope boundaries:\n - No authentication for private vals, no editing/workspace features.\n - Multi-val/project aggregation and version diffing remain out of scope for v1.\n - UI polish limited to Tailwind-based theming without custom theming engine.\n\n## Analysis\n\n- Key components and responsibilities (to be created under `/backend`, `/frontend`, `/shared` as per AGENTS guidelines):\n - [backend/docGenerator.http.ts](/backend/docGenerator.http.ts#L1-L200) — Planned Hono HTTP entrypoint orchestrating fetch → parse → cache → render.\n - [backend/services/valFetcher.ts](/backend/services/valFetcher.ts#L1-L200) — Planned Val Town API client resolving val metadata and source bundle.\n - [backend/services/tsParser.ts](/backend/services/tsParser.ts#L1-L300) — Planned TypeScript compiler API walker emitting `ParsedDocumentation`.\n - [backend/services/docCache.ts](/backend/services/docCache.ts#L1-L160) — Planned blob-backed cache with memory front.\n - [shared/docTypes.ts](/shared/docTypes.ts#L1-L200) — Planned shared TypeScript interfaces for parser output and UI consumption.\n - [frontend/index.html](/frontend/index.html#L1-L200) & [frontend/App.tsx](/frontend/App.tsx#L1-L200) — Planned React shell rendering docs, search, and navigation.\n- Data/types affected:\n - `DocManifest`, `FunctionDoc`, `TypeDoc`, `ClassDoc`, `ConstantDoc`, `ImportInfo`; caching metadata `{ cacheKey: string; createdAt: number; version: string; }`.\n - Request DTO `{ val: string; refresh?: boolean }`, error envelope `{ code: string; message: string; details?: unknown }`.\n- Current flow:\n 1. Request enters Hono → query param validation.\n 2. Cache lookup by `valIdentifier@version` (memory → blob fallback).\n 3. On miss: fetch val metadata + files → parse AST → build manifest → persist cache.\n 4. API route returns JSON; UI route hydrates React with initial manifest + fetch fallback.\n\n## Approach\n\n- Establish shared documentation schemas and validation helpers first so backend and frontend contract is locked before logic work.\n- Implement val fetching and caching seams prior to TypeScript parsing to minimize external API pressure and enable testability via fixtures.\n- Build the TypeScript parser as a pure module with exhaustive unit tests, then integrate into the fetcher pipeline behind cache lookups.\n- Compose the Hono HTTP val with separate API (`/api/docs`) and UI (`/`) routes, injecting fetch/parse/cache services for easy stubbing.\n- Deliver the React/Twind frontend last, hydrating with server-injected manifest while supporting client-side refresh via the API.\n- Assumptions: `npm:typescript` bundling works in Val Town serverless context; Val Town REST endpoints for public vals require no auth; Tailwind via Twind CDN is acceptable for styling.\n\n## Step-by-Step Implementation\n\n> Sequence logically: refactor → scaffold → integrate (flagged) → validate → cleanup.\n\n### Step 1 — Define shared documentation contract\n\n**Intent:** Lock parser ↔ renderer contract and validation helpers before logic diverges.\n**Files:** [shared/docTypes.ts](/shared/docTypes.ts#L1-L200), [shared/docTypes.test.ts](/shared/docTypes.test.ts#L1-L160)\n**Change sketch:**\n\n```diff\n+ export interface DocManifest {\n+ val: string;\n+ version: string;\n+ generatedAt: string;\n+ exports: {\n+ functions: FunctionDoc[];\n+ classes: ClassDoc[];\n+ interfaces: InterfaceDoc[];\n+ types: TypeAliasDoc[];\n+ constants: ConstantDoc[];\n+ };\n+ imports: ImportInfo[];\n+ metadata: ValMetadata;\n+ }\n+\n+ export function assertDocManifest(data: unknown): asserts data is DocManifest {\n+ // runtime validation leveraging type predicates or zod-like helper (decide on zod dependency vs hand-rolled guards)\n+ }\n```\n\n**Preconditions:** None.\n**Postconditions:** Typed contract with runtime guard available for backend and frontend.\n**Checks:** Unit tests covering validation happy path and failure scenarios.\n\n### Step 2 — Scaffold Val Town fetcher and cache seams\n\n**Intent:** Provide deterministic data sources and caching hooks prior to parser integration.\n**Files:** [backend/services/valFetcher.ts](/backend/services/valFetcher.ts#L1-L200), [backend/services/docCache.ts](/backend/services/docCache.ts#L1-L200), [backend/services/**tests**/valFetcher.test.ts](/backend/services/__tests__/valFetcher.test.ts#L1-L200)\n**Change sketch:**\n\n```diff\n+ export interface ValFetcher {\n+ fetchLatest(val: string): Promise;\n+ }\n+\n+ export const docCache = createDocCache({\n+ ttlMs: 60 * 60 * 1000,\n+ blobPrefix: \"doc-manifest\",\n+ });\n```\n\n**Preconditions:** Step 1 contract finalized.\n**Postconditions:** Fetcher returns mocked data in tests; cache exposes get/set/isFresh with blob-backed implementation (no parser usage yet).\n**Checks:** Unit tests hitting Val Town API via mocked fetch; cache tests verifying TTL & key derivation.\n\n### Step 3 — Implement TypeScript parser module\n\n**Intent:** Build pure parsing logic producing the shared manifest structures without I/O coupling.\n**Files:** [backend/services/tsParser.ts](/backend/services/tsParser.ts#L1-L300), [backend/services/**tests**/tsParser.test.ts](/backend/services/__tests__/tsParser.test.ts#L1-L300), [test-fixtures/vals/simple.ts](/test-fixtures/vals/simple.ts#L1-L200)\n**Change sketch:**\n\n```diff\n+ export function parseValBundle(bundle: ValBundle): DocManifest {\n+ const program = ts.createProgram(\n+ bundle.files.map((file) => file.path),\n+ compilerOptions,\n+ createInMemoryCompilerHost(bundle)\n+ );\n+ // walk AST, fill manifest.exports\n+ return manifest;\n+ }\n```\n\n**Preconditions:** Step 1 types available; Step 2 supplies ValBundle shape.\n**Postconditions:** Parser returns manifest for fixture bundles with deterministic ordering; no cache integration yet.\n**Checks:** Unit tests for functions, classes, interfaces, type aliases, constants, malformed inputs.\n\n### Step 4 — Compose doc generation pipeline with caching\n\n**Intent:** Integrate fetcher, parser, and cache into orchestrated service exposing `generateDocs`, caching manifests and prerendered HTML for <3s responses.\n**Files:** [backend/services/docService.ts](/backend/services/docService.ts#L1-L200), [backend/services/**tests**/docService.test.ts](/backend/services/__tests__/docService.test.ts#L1-L200)\n**Change sketch:**\n\n```diff\n+ export interface CachedDocPayload {\n+ manifest: DocManifest;\n+ ssrHtml?: string;\n+ cachedAt: number;\n+ }\n+\n+ export async function generateDocs(val: string, opts: { refresh?: boolean }) {\n+ const cacheKey = deriveCacheKey(val);\n+ if (!opts.refresh) {\n+ const cached = await docCache.get(cacheKey);\n+ if (cached && !docCache.isExpired(cacheKey)) return cached;\n+ }\n+ const bundle = await valFetcher.fetchLatest(val);\n+ const manifest = parseValBundle(bundle);\n+ const payload: CachedDocPayload = { manifest, cachedAt: Date.now() };\n+ await docCache.set(cacheKey, payload, { version: bundle.version });\n+ return payload;\n+ }\n```\n\n**Preconditions:** Steps 1–3 merged.\n**Postconditions:** Single orchestration entry point with cache hit logging hook, rate-limited fetch usage; cached payload reusable for API and UI routes.\n**Checks:** Service tests mocking cache/fetcher to assert cache strategy, ttl handling, and refresh behavior.\n\n### Step 5 — Build Hono HTTP val routes\n\n**Intent:** Expose API and UI endpoints leveraging docService; ensure error handling & logging.\n**Files:** [backend/docGenerator.http.ts](/backend/docGenerator.http.ts#L1-L200), [backend/routes/apiDocs.ts](/backend/routes/apiDocs.ts#L1-L200), [backend/routes/ui.ts](/backend/routes/ui.ts#L1-L200), [backend/routes/**tests**/apiDocs.test.ts](/backend/routes/__tests__/apiDocs.test.ts#L1-L200)\n**Change sketch:**\n\n```diff\n+ app.get(\"/api/docs\", async (c) => {\n+ const val = c.req.query(\"val\");\n+ if (!val) return c.json({ code: \"BAD_REQUEST\" }, 400);\n+ const { manifest } = await generateDocs(val, { refresh: c.req.query(\"refresh\") === \"true\" });\n+ return c.json(manifest);\n+ });\n+\n+ app.get(\"/\", async (c) => {\n+ const initialVal = c.req.query(\"val\");\n+ const cached = initialVal ? await generateDocs(initialVal, { refresh: false }) : null;\n+ if (!cached?.manifest) {\n+ const emptyHtml = await renderIndexPage({ manifest: null, val: initialVal });\n+ return c.html(emptyHtml);\n+ }\n+ if (!cached.ssrHtml) {\n+ cached.ssrHtml = await renderIndexPage({ manifest: cached.manifest, val: initialVal });\n+ await docCache.set(deriveCacheKey(initialVal), cached, { version: cached.manifest.version });\n+ }\n+ return c.html(cached.ssrHtml);\n+ });\n```\n\n**Preconditions:** Step 4 ready.\n**Postconditions:** HTTP val deployed with API contract, SSR injecting initial manifest, error states handled.\n**Checks:** Integration tests via superdeno hitting API and root route; lint/typecheck.\n\n### Step 6 — Implement React/Twind frontend shell\n\n**Intent:** Deliver interactive documentation UI consuming manifest and supporting client fetch refresh.\n**Files:** [frontend/index.html](/frontend/index.html#L1-L200), [frontend/App.tsx](/frontend/App.tsx#L1-L200), [frontend/components/FunctionDoc.tsx](/frontend/components/FunctionDoc.tsx#L1-L200), [frontend/components/Sidebar.tsx](/frontend/components/Sidebar.tsx#L1-L200), [frontend/**tests**/App.test.tsx](/frontend/__tests__/App.test.tsx#L1-L200)\n**Change sketch:**\n\n```diff\n+ /** @jsxImportSource https://esm.sh/react@18.2.0 */\n+ import { useEffect, useState } from \"https://esm.sh/react@18.2.0\";\n+ export function App(props: { initialManifest?: DocManifest; initialVal?: string }) {\n+ const [manifest, setManifest] = useState(props.initialManifest ?? null);\n+ // render header, sidebar, main, search, dark mode toggle\n+ }\n```\n\n**Preconditions:** Step 5 HTML render helper able to inject `initialManifest`.\n**Postconditions:** Responsive UI with search/filter, syntax highlighting via Prism/Twind, copy-to-clipboard.\n**Checks:** Frontend unit tests with pre-rendered manifest, visual smoke test in Val Town.\n\n### Step 7 — Telemetry, rate limiting, and documentation\n\n**Intent:** Add request logging, cache hit metrics, rate limiting guard, and README instructions.\n**Files:** [backend/services/logger.ts](/backend/services/logger.ts#L1-L120), [backend/docGenerator.http.ts](/backend/docGenerator.http.ts#L1-L200), [README.md](/README.md#L1-L200)\n**Change sketch:**\n\n```diff\n+ app.use(\"/api/docs\", rateLimit({ windowMs: 60_000, max: 30 }));\n+ logger.info({ event: \"doc_cache_hit\", val, cacheKey });\n+ logger.info({ event: \"doc_cache_miss\", val, durationMs });\n+\n+## Usage\n+- Deploy `docGenerator` via Val Town HTTP val.\n```\n\n**Preconditions:** Core functionality stable (Steps 1–6).\n**Postconditions:** Observability and docs in place; rate limiting prevents abuse.\n**Checks:** Manual smoke tests, documentation review.\n\n## Open Questions\n\n- Confirm whether we must support fetching specific val versions (e.g., `?version=` query) in v1 or default to latest only.\n- Clarify if Tailwind via Twind CDN is acceptable for production or if inline Tailwind build step is preferred.\n- Determine acceptable rate limit thresholds and logging retention (where should logs emit?).\n\n## Resources\n\n- Build/test: `deno task check`, `deno test`, `deno lint`, `biome check .`\n- Docs: [Val Town API](https://docs.val.town/api/overview), [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API), [TSDoc Spec](https://tsdoc.org/).\n- Reference vals: `https://www.val.town/v/std/utils@85-main/index.ts`, `https://www.val.town/v/std/blob`.\n","label",[138],"ab859064-c400-11f0-84ab-42dde27851f2","test.ts","0ee6d226-c3f7-11f0-be52-42dde27851f2",117,["D",1763416760432],38,"import ValTown from \"npm:@valtown/sdk@latest\";\nconst client = new ValTown();\nconst val = await client.alias.username.valName.retrieve(\"oauth\", {\n username: \"std\",\n});\n\nconsole.log(val.id);",[149],"93b52b40-c417-11f0-870f-42dde27851f2","deno.json","cab598f4-c3dc-11f0-9928-42dde27851f2",141,["D",1763426598971],4,"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n \"compilerOptions\": {\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ],\n \"jsx\": \"react-jsx\",\n \"jsxImportSource\": \"https://esm.sh/react@18.2.0\",\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n },\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-sloppy-imports\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true\n },\n \"imports\": {\n \"@biomejs/biome\": \"npm:@biomejs/biome@^2.3.6\",\n \"@valtown/sdk\": \"npm:@valtown/sdk@^0.36.0\"\n },\n \"lint\": {\n \"files\": {\n \"include\": [\"deno:/https/esm.town/**/*\"]\n },\n \"rules\": {\n \"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n }\n },\n \"lock\": false,\n \"nodeModulesDir\": \"auto\"\n}\n",[157],"c244e47e-c3f3-11f0-8584-42dde27851f2","biome.json","cac88aea-c3dc-11f0-963c-42dde27851f2",43,["D",1763411215215],"{\n\t\"$schema\": \"https://biomejs.dev/schemas/2.3.6/schema.json\",\n\t\"vcs\": {\n\t\t\"enabled\": false,\n\t\t\"clientKind\": \"git\",\n\t\t\"useIgnoreFile\": false\n\t},\n\t\"files\": {\n\t\t\"ignoreUnknown\": false\n\t},\n\t\"formatter\": {\n\t\t\"enabled\": true,\n\t\t\"indentStyle\": \"tab\"\n\t},\n\t\"linter\": {\n\t\t\"enabled\": true,\n\t\t\"rules\": {\n\t\t\t\"recommended\": true\n\t\t}\n\t},\n\t\"javascript\": {\n\t\t\"formatter\": {\n\t\t\t\"quoteStyle\": \"double\"\n\t\t}\n\t},\n\t\"assist\": {\n\t\t\"enabled\": true,\n\t\t\"actions\": {\n\t\t\t\"source\": {\n\t\t\t\t\"organizeImports\": \"on\"\n\t\t\t}\n\t\t}\n\t}\n}\n",[165],"d2fdb60a-c403-11f0-9f4b-42dde27851f2","README.md","ccebd50e-c3e4-11f0-b9d5-42dde27851f2",128,["D",1763418115219],"# Val Town Documentation Generator\n\nAutomatically generate beautiful, interactive documentation for your Val Town\nvals by parsing TypeScript AST and extracting functions, classes, interfaces,\ntypes, and constants with their JSDoc comments.\n\n## Features\n\n- 📝 **Automatic Code Parsing** - Extracts functions, classes, interfaces, type\n aliases, and constants\n- 💬 **JSDoc Support** - Parses `@param`, `@returns`, `@example`, and\n `@deprecated` tags\n- 🔍 **Search & Filter** - Quickly find what you're looking for\n- ⚡ **Fast Caching** - Sub-second responses for cached documentation (1-hour\n TTL)\n- 🎨 **Clean UI** - Responsive design with Tailwind CSS via Twind\n- 🚀 **Serverless** - Runs on Val Town's serverless platform\n\n## Usage\n\n### API Endpoint\n\nGenerate documentation JSON for any public val:\n\n```\nGET /api/docs?val=username/valname\n```\n\n**Query Parameters:**\n\n- `val` (required) - Val identifier in format `username/valname`\n- `refresh` (optional) - Set to `true` to bypass cache\n\n**Example:**\n\n```bash\ncurl \"https://docs-gen.val.run/api/docs?val=stevekrouse/example\"\n```\n\n**Response:**\n\n```json\n{\n \"val\": \"stevekrouse/example\",\n \"version\": \"1\",\n \"generatedAt\": \"2025-11-17T12:00:00.000Z\",\n \"exports\": {\n \"functions\": [...],\n \"classes\": [...],\n \"interfaces\": [...],\n \"types\": [...],\n \"constants\": [...]\n },\n \"imports\": [...],\n \"metadata\": {...}\n}\n```\n\n### Web UI\n\nVisit the root URL with a val query parameter to view interactive documentation:\n\n```\nhttps://docs-gen.val.run/?val=username/valname\n```\n\nThe UI provides:\n\n- Searchable sidebar navigation\n- Syntax-highlighted code examples\n- Detailed parameter and return type information\n- JSDoc comment rendering\n- Direct links to source code locations\n\n## Project Structure\n\n```\n.\n├── backend/\n│ ├── docGenerator.http.ts # Main HTTP entry point\n│ ├── routes/\n│ │ ├── apiDocs.ts # API route handler\n│ │ └── ui.ts # UI route handler\n│ └── services/\n│ ├── docCache.ts # Blob-backed cache with memory front\n│ ├── docService.ts # Main orchestration service\n│ ├── tsParser.ts # TypeScript AST parser\n│ └── valFetcher.ts # Val Town API client\n├── frontend/\n│ ├── index.html # HTML entry point\n│ ├── index.tsx # React app entry\n│ └── components/ # React UI components\n│ ├── App.tsx\n│ ├── Header.tsx\n│ ├── Sidebar.tsx\n│ ├── MainContent.tsx\n│ ├── FunctionDocCard.tsx\n│ ├── ClassDocCard.tsx\n│ ├── InterfaceDocCard.tsx\n│ ├── TypeDocCard.tsx\n│ ├── ConstantDocCard.tsx\n│ ├── CodeBlock.tsx\n│ └── DocCommentDisplay.tsx\n└── shared/\n └── docTypes.ts # Shared TypeScript types\n```\n\n## Architecture\n\n### 1. Request Flow\n\n1. **Request** → Hono HTTP val receives request\n2. **Cache Check** → Check memory cache, then blob storage\n3. **On Cache Miss:**\n - Fetch val metadata from Val Town API\n - Fetch source code from esm.town\n - Parse TypeScript AST to extract documentation\n - Cache result in blob storage and memory\n4. **Response** → Return JSON (API) or rendered HTML (UI)\n\n### 2. Caching Strategy\n\n- **Memory Cache**: LRU cache (100 entries) for hot paths\n- **Blob Storage**: Persistent cache with 1-hour TTL\n- **Cache Key**: Derived from `username/valname@version`\n- **Cache Hit Performance**: ~20ms\n- **Cache Miss**: ~2-3 seconds (includes API calls and parsing)\n\n### 3. TypeScript Parsing\n\nUses the TypeScript Compiler API to:\n\n- Create an in-memory compiler host\n- Parse source files into AST\n- Walk nodes to extract declarations\n- Parse JSDoc comments using `ts.getJSDocTags()`\n- Generate type signatures and metadata\n\n## API Documentation\n\n### Types\n\nSee `shared/docTypes.ts` for complete type definitions:\n\n- `DocManifest` - Main documentation manifest\n- `FunctionDoc` - Function documentation\n- `ClassDoc` - Class documentation\n- `InterfaceDoc` - Interface documentation\n- `TypeAliasDoc` - Type alias documentation\n- `ConstantDoc` - Constant/variable documentation\n- `DocComment` - Parsed JSDoc comment\n- `ValMetadata` - Val Town metadata\n\n### Services\n\n#### `docService.ts`\n\nMain orchestration service:\n\n```typescript\n// Generate docs with caching\nawait generateDocs(val: string, opts?: { refresh?: boolean })\n\n// Refresh cache\nawait refreshDocs(val: string)\n\n// Get cached docs only\nawait getCachedDocs(val: string)\n\n// Clear cache\nawait clearValCache(val: string)\nawait clearAllCaches()\n```\n\n#### `valFetcher.ts`\n\nVal Town API client:\n\n```typescript\n// Fetch val bundle\nawait valFetcher.fetchLatest(val: string): Promise\n```\n\n#### `tsParser.ts`\n\nTypeScript AST parser:\n\n```typescript\n// Parse val bundle to documentation\nparseValBundle(bundle: ValBundle): DocManifest\n```\n\n#### `docCache.ts`\n\nDocumentation cache:\n\n```typescript\n// Create cache instance\nconst cache = createDocCache({ ttlMs: 3600000, blobPrefix: \"doc-cache\" })\n\n// Cache operations\nawait cache.get(key: string)\nawait cache.set(key: string, data: T, metadata: { version: string })\nawait cache.has(key: string)\nawait cache.delete(key: string)\n```\n\n## Development\n\n### Testing Locally\n\n1. Clone this repository\n2. Deploy to Val Town as an HTTP val\n3. Test with a public val:\n ```\n https://docs-gen.val.run/?val=stevekrouse/example\n ```\n\n### Deployment\n\nThis project is designed to run as a Val Town HTTP val. The entry point is\n`backend/docGenerator.http.ts`.\n\nTo deploy:\n\n1. Create a new HTTP val in Val Town\n2. Copy the entire project structure\n3. Point to `backend/docGenerator.http.ts` as the entry point\n\n## Performance\n\n- **First Request** (cache miss): 2-3 seconds\n- **Cached Request**: 20-50ms\n- **Cache TTL**: 1 hour\n- **API Calls per Request**: Max 2 (metadata + source)\n\n## Limitations\n\n- **Public vals only** - No authentication for private vals\n- **Single file vals** - Multi-file projects not yet supported\n- **Basic syntax highlighting** - No Prism.js integration yet\n- **No version history** - Only latest version supported\n- **Rate limiting** - Not yet implemented (planned)\n\n## Future Enhancements\n\n- [ ] Rate limiting to prevent abuse\n- [ ] Support for private vals with authentication\n- [ ] Multi-file val/project support\n- [ ] Version history and diffing\n- [ ] Enhanced syntax highlighting with Prism.js\n- [ ] Export to Markdown\n- [ ] Custom theming\n- [ ] Metrics and analytics dashboard\n\n## Contributing\n\nThis is a Val Town project. To contribute:\n\n1. Fork the val\n2. Make your changes\n3. Test thoroughly\n4. Submit a pull request with clear description\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Credits\n\nBuilt with:\n\n- [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)\n- [Hono](https://hono.dev/) - Web framework\n- [React](https://react.dev/) - UI library\n- [Twind](https://twind.style/) - Tailwind CSS-in-JS\n- [Val Town](https://val.town/) - Serverless platform\n\n---\n\n**Need help?** Open an issue or reach out on Val Town Discord.",[172],"cabf6d48-c3dc-11f0-8d89-42dde27851f2","AGENTS.md","cabf6dfc-c3dc-11f0-8d89-42dde27851f2",3,["D",1763401351018],"You are an advanced assistant specialized in generating Val Town code.\n\n## Core Guidelines\n\n- Ask clarifying questions when requirements are ambiguous\n- Provide complete, functional solutions rather than skeleton implementations\n- Test your logic against edge cases before presenting the final solution\n- Ensure all code follows Val Town's specific platform requirements\n- If a section of code that you're working on is getting too complex, consider\n refactoring it into subcomponents\n\n## Code Standards\n\n- Generate code in TypeScript or TSX\n- Add appropriate TypeScript types and interfaces for all data structures\n- Prefer official SDKs or libraries than writing API calls directly\n- Ask the user to supply API or library documentation if you are at all unsure\n about it\n- **Never bake in secrets into the code** - always use environment variables\n- Include comments explaining complex logic (avoid commenting obvious\n operations)\n- Follow modern ES6+ conventions and functional programming practices if\n possible\n\n## Types of triggers\n\n### 1. HTTP Trigger\n\n- Create web APIs and endpoints\n- Handle HTTP requests and responses\n- Example structure:\n\n```ts\nexport default async function (req: Request) {\n return new Response(\"Hello World\");\n}\n```\n\nFiles that are HTTP triggers have http in their name like `foobar.http.tsx`\n\n### 2. Cron Triggers\n\n- Run on a schedule\n- Use cron expressions for timing\n- Example structure:\n\n```ts\nexport default async function () {\n // Scheduled task code\n}\n```\n\nFiles that are Cron triggers have cron in their name like `foobar.cron.tsx`\n\n### 3. Email Triggers\n\n- Process incoming emails\n- Handle email-based workflows\n- Example structure:\n\n```ts\nexport default async function (email: Email) {\n // Process email\n}\n```\n\nFiles that are Email triggers have email in their name like `foobar.email.tsx`\n\n## Val Town Standard Libraries\n\nVal Town provides several hosted services and utility functions.\n\n### Blob Storage\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\nawait blob.setJSON(\"myKey\", { hello: \"world\" });\nlet blobDemo = await blob.getJSON(\"myKey\");\nlet appKeys = await blob.list(\"app_\");\nawait blob.delete(\"myKey\");\n```\n\n### SQLite\n\n```ts\nimport { sqlite } from \"https://esm.town/v/stevekrouse/sqlite\";\nconst TABLE_NAME = \"todo_app_users_2\";\n// Create table - do this before usage and change table name when modifying schema\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL\n)`);\n// Query data\nconst result = await sqlite.execute(\n `SELECT * FROM ${TABLE_NAME} WHERE id = ?`,\n [1],\n);\n```\n\nNote: When changing a SQLite table's schema, change the table's name (e.g., add\n_2 or _3) to create a fresh table.\n\n### OpenAI\n\n```ts\nimport { OpenAI } from \"https://esm.town/v/std/openai\";\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n messages: [\n { role: \"user\", content: \"Say hello in a creative way\" },\n ],\n model: \"gpt-4o-mini\",\n max_tokens: 30,\n});\n```\n\n### Email\n\n```ts\nimport { email } from \"https://esm.town/v/std/email\";\n// By default emails the owner of the val\nawait email({\n subject: \"Hi\",\n text: \"Hi\",\n html: \"

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`",[179],"cac32640-c3dc-11f0-9928-42dde27851f2",".vtignore","cac3271c-c3dc-11f0-9928-42dde27851f2",["D",1763401351042],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor",[186],"cc47c946-c3e4-11f0-8a14-42dde27851f2","shared","cc47c9fa-c3e4-11f0-8a14-42dde27851f2",11,["D",1763404789566],"directory",[192],"cc29d652-c3e4-11f0-8a14-42dde27851f2","frontend","cc29d738-c3e4-11f0-8a14-42dde27851f2",9,["D",1763404789368],[199],"cc382342-c3e4-11f0-8a14-42dde27851f2","backend","cc382428-c3e4-11f0-8a14-42dde27851f2",10,["D",1763404789463],[205],"pulls","branches","forks","envVars",{"_217":144,"_219":64},"connections",{"_217":64,"_218":64},"count","unfilledCount","emptyCount",{"_44":204,"_32":205,"_30":206,"_140":-5,"_42":43,"_41":207,"_142":60,"_39":488,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_257":489,"_27":490},{"_44":483,"_32":474,"_30":468,"_140":206,"_42":43,"_41":484,"_142":60,"_39":485,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_257":486,"_27":487},{"_44":475,"_32":476,"_30":477,"_140":468,"_42":43,"_41":478,"_142":60,"_39":479,"_13":144,"_34":35,"_36":480,"_24":25,"_146":-5,"_257":481,"_27":482},{"_44":465,"_32":466,"_30":467,"_140":468,"_42":43,"_41":469,"_142":60,"_39":470,"_13":144,"_34":35,"_36":471,"_24":25,"_146":-5,"_257":472,"_27":473},{"_44":460,"_32":435,"_30":430,"_140":206,"_42":43,"_41":461,"_142":60,"_39":462,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_257":463,"_27":464},{"_44":452,"_32":453,"_30":454,"_140":430,"_42":43,"_41":455,"_142":60,"_39":456,"_13":144,"_34":35,"_36":457,"_24":25,"_146":-5,"_257":458,"_27":459},{"_44":444,"_32":445,"_30":446,"_140":430,"_42":43,"_41":447,"_142":25,"_39":448,"_13":64,"_34":35,"_36":449,"_24":25,"_146":-5,"_257":450,"_27":451},{"_44":436,"_32":437,"_30":438,"_140":430,"_42":43,"_41":439,"_142":60,"_39":440,"_13":207,"_34":35,"_36":441,"_24":25,"_146":-5,"_257":442,"_27":443},{"_44":429,"_32":33,"_30":31,"_140":430,"_42":43,"_41":14,"_142":60,"_39":431,"_13":432,"_34":35,"_36":38,"_24":25,"_146":-5,"_257":433,"_27":434},{"_44":421,"_32":422,"_30":58,"_140":206,"_42":43,"_41":423,"_142":60,"_39":424,"_13":144,"_34":425,"_36":426,"_24":25,"_146":46,"_257":427,"_27":428},{"_44":198,"_32":199,"_30":200,"_140":-5,"_42":43,"_41":201,"_142":60,"_39":418,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_257":419,"_27":420},{"_44":413,"_32":315,"_30":309,"_140":200,"_42":43,"_41":414,"_142":60,"_39":415,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_257":416,"_27":417},{"_44":404,"_32":405,"_30":406,"_140":309,"_42":43,"_41":407,"_142":25,"_39":408,"_13":409,"_34":35,"_36":410,"_24":25,"_146":-5,"_257":411,"_27":412},{"_44":396,"_32":397,"_30":398,"_140":309,"_42":43,"_41":399,"_142":60,"_39":400,"_13":144,"_34":35,"_36":401,"_24":25,"_146":-5,"_257":402,"_27":403},{"_44":388,"_32":389,"_30":390,"_140":309,"_42":43,"_41":391,"_142":60,"_39":392,"_13":144,"_34":35,"_36":393,"_24":25,"_146":-5,"_257":394,"_27":395},{"_44":380,"_32":381,"_30":382,"_140":309,"_42":43,"_41":383,"_142":60,"_39":384,"_13":144,"_34":35,"_36":385,"_24":25,"_146":-5,"_257":386,"_27":387},{"_44":372,"_32":373,"_30":374,"_140":309,"_42":43,"_41":375,"_142":25,"_39":376,"_13":144,"_34":35,"_36":377,"_24":25,"_146":-5,"_257":378,"_27":379},{"_44":364,"_32":365,"_30":366,"_140":309,"_42":43,"_41":367,"_142":60,"_39":368,"_13":144,"_34":35,"_36":369,"_24":25,"_146":-5,"_257":370,"_27":371},{"_44":356,"_32":357,"_30":358,"_140":309,"_42":43,"_41":359,"_142":60,"_39":360,"_13":144,"_34":35,"_36":361,"_24":25,"_146":-5,"_257":362,"_27":363},{"_44":348,"_32":349,"_30":350,"_140":309,"_42":43,"_41":351,"_142":60,"_39":352,"_13":302,"_34":35,"_36":353,"_24":25,"_146":-5,"_257":354,"_27":355},{"_44":340,"_32":341,"_30":342,"_140":309,"_42":43,"_41":343,"_142":60,"_39":344,"_13":144,"_34":35,"_36":345,"_24":25,"_146":-5,"_257":346,"_27":347},{"_44":332,"_32":333,"_30":334,"_140":309,"_42":43,"_41":335,"_142":60,"_39":336,"_13":144,"_34":35,"_36":337,"_24":25,"_146":-5,"_257":338,"_27":339},{"_44":324,"_32":325,"_30":326,"_140":309,"_42":43,"_41":327,"_142":60,"_39":328,"_13":144,"_34":35,"_36":329,"_24":25,"_146":-5,"_257":330,"_27":331},{"_44":316,"_32":317,"_30":318,"_140":309,"_42":43,"_41":319,"_142":60,"_39":320,"_13":161,"_34":35,"_36":321,"_24":25,"_146":-5,"_257":322,"_27":323},{"_44":306,"_32":307,"_30":308,"_140":309,"_42":43,"_41":310,"_142":60,"_39":311,"_13":144,"_34":35,"_36":312,"_24":25,"_146":-5,"_257":313,"_27":314},{"_44":297,"_32":298,"_30":299,"_140":200,"_42":43,"_41":300,"_142":60,"_39":301,"_13":302,"_34":20,"_36":303,"_24":25,"_146":-5,"_257":304,"_27":305},{"_44":289,"_32":290,"_30":291,"_140":200,"_42":43,"_41":292,"_142":25,"_39":293,"_13":144,"_34":35,"_36":294,"_24":25,"_146":-5,"_257":295,"_27":296},{"_44":191,"_32":192,"_30":193,"_140":-5,"_42":43,"_41":194,"_142":60,"_39":286,"_13":64,"_34":196,"_36":-5,"_24":25,"_146":-5,"_257":287,"_27":288},{"_44":278,"_32":279,"_30":280,"_140":193,"_42":43,"_41":281,"_142":60,"_39":282,"_13":181,"_34":35,"_36":283,"_24":25,"_146":-5,"_257":284,"_27":285},{"_44":185,"_32":186,"_30":187,"_140":-5,"_42":43,"_41":161,"_142":60,"_39":275,"_13":64,"_34":20,"_36":189,"_24":25,"_146":-5,"_257":276,"_27":277},{"_44":178,"_32":179,"_30":180,"_140":-5,"_42":43,"_41":181,"_142":60,"_39":272,"_13":64,"_34":20,"_36":183,"_24":25,"_146":-5,"_257":273,"_27":274},{"_44":171,"_32":172,"_30":173,"_140":-5,"_42":43,"_41":174,"_142":25,"_39":269,"_13":144,"_34":20,"_36":176,"_24":25,"_146":-5,"_257":270,"_27":271},{"_44":164,"_32":165,"_30":166,"_140":-5,"_42":43,"_41":167,"_142":25,"_39":266,"_13":144,"_34":20,"_36":169,"_24":25,"_146":-5,"_257":267,"_27":268},{"_44":156,"_32":157,"_30":158,"_140":-5,"_42":43,"_41":159,"_142":60,"_39":263,"_13":161,"_34":20,"_36":162,"_24":25,"_146":-5,"_257":264,"_27":265},{"_44":148,"_32":149,"_30":150,"_140":-5,"_42":43,"_41":151,"_142":25,"_39":260,"_13":153,"_34":35,"_36":154,"_24":25,"_146":-5,"_257":261,"_27":262},{"_44":137,"_32":138,"_30":139,"_140":-5,"_42":43,"_41":141,"_142":60,"_39":256,"_13":144,"_34":20,"_36":145,"_24":25,"_146":-5,"_257":258,"_27":259},["D",1763402806837],"children",[],[138],["D",1763416760432],[],[149],["D",1763426598971],[],[157],["D",1763411215215],[],[165],["D",1763418115219],[],[172],["D",1763401351018],[],[179],["D",1763401351042],[],[186],"93f28e72-c417-11f0-ba79-42dde27851f2","docTypes.ts","cce74336-c3e4-11f0-b160-42dde27851f2",148,["D",1763426599382],"/**\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",[],[192,279],["D",1763404789566],[248],[192],"936ce452-c417-11f0-97cd-42dde27851f2","index.tsx","cc81213c-c3e4-11f0-8120-42dde27851f2",131,["D",1763426598493],"/** @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 throw new Error(\"Failed to find the root element\");\n}\nconst root = createRoot(rootElement);\nroot.render(\n \n \n ,\n);\n",[],[199,290],"a03dd340-c3f3-11f0-bbb3-42dde27851f2","index.html","cc8da1a0-c3e4-11f0-85f8-42dde27851f2",42,["D",1763411158044],2,"\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",[],[199,298],"9364ead6-c417-11f0-bcdc-42dde27851f2","TypeDocCard.tsx","ccf5ec60-c3e4-11f0-8a14-42dde27851f2","cc53b332-c3e4-11f0-8a14-42dde27851f2",129,["D",1763426598456],"/** @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",[],[199,315,307],"components","93a41cba-c417-11f0-bffa-42dde27851f2","Sidebar.tsx","ccbebcd6-c3e4-11f0-85f8-42dde27851f2",139,["D",1763426598868],"/** @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",[],[199,315,317],"939cdf0e-c417-11f0-a7c0-42dde27851f2","MainContent.tsx","ccb3ca7e-c3e4-11f0-b160-42dde27851f2",138,["D",1763426598761],"/** @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",[],[199,315,325],"939051bc-c417-11f0-97cd-42dde27851f2","LoadingSpinner.tsx","ccb1280a-c3e4-11f0-a716-42dde27851f2",137,["D",1763426598702],"/** @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",[],[199,315,333],"9387e3f6-c417-11f0-8d87-42dde27851f2","InterfaceDocCard.tsx","ccaa9c1a-c3e4-11f0-b9d5-42dde27851f2",136,["D",1763426598673],"/** @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",[],[199,315,341],"93c77f20-c417-11f0-b031-42dde27851f2","Header.tsx","ccba8936-c3e4-11f0-b9d5-42dde27851f2",144,["D",1763426598764],"/** @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",[],[199,315,349],"937d478e-c417-11f0-ba79-42dde27851f2","FunctionDocCard.tsx","cc9d0a1e-c3e4-11f0-85f8-42dde27851f2",135,["D",1763426598614],"/** @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",[],[199,315,357],"937979a6-c417-11f0-83a9-42dde27851f2","ErrorMessage.tsx","cca3fa40-c3e4-11f0-83ba-42dde27851f2",134,["D",1763426598573],"/** @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",[],[199,315,365],"0f59a434-c403-11f0-917b-42dde27851f2","DocCommentDisplay.tsx","ccad40e6-c3e4-11f0-85f8-42dde27851f2",124,["D",1763417786985],"/** @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",[],[199,315,373],"93720f18-c417-11f0-ba79-42dde27851f2","ConstantDocCard.tsx","cca0bcea-c3e4-11f0-8120-42dde27851f2",132,["D",1763426598529],"/** @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",[],[199,315,381],"93a99c12-c417-11f0-870f-42dde27851f2","CodeBlock.tsx","cccaa2b2-c3e4-11f0-a716-42dde27851f2",140,["D",1763426598879],"/** @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",[],[199,315,389],"93758328-c417-11f0-bcdc-42dde27851f2","ClassDocCard.tsx","cc959324-c3e4-11f0-982c-42dde27851f2",133,["D",1763426598491],"/** @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",[],[199,315,397],"9368a5b8-c417-11f0-ba79-42dde27851f2","App.tsx","cc86876c-c3e4-11f0-83ba-42dde27851f2",130,["D",1763426598476],5,"/** @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 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 \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",[],[199,315,405],"cc53b27e-c3e4-11f0-8a14-42dde27851f2",12,["D",1763404789643],[232,233,234,235,236,237,238,239,240,241,242,243,244],[199,315],["D",1763404789368],[231,245,246],[199],"93bceed4-c417-11f0-ba79-42dde27851f2","docGenerator.http.ts",142,["D",1763426598996],"http","/**\n * Val Town Documentation Generator\n *\n * Main HTTP val entry point for the documentation generation service.\n *\n * ## Routes\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 * - `GET /health` - Health check endpoint\n */\n\nimport { serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport { Hono } from \"npm:hono@4.0.0\";\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// API Routes\napp.get(\"/api/docs\", getApiDocs);\n\n// UI Routes\napp.get(\"/\", getUI);\n\n// Static File Serving\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 *\n * @param c - Hono context\n * @returns JSON response with status and timestamp\n */\napp.get(\"/health\", (c) => {\n return c.json({\n status: \"ok\",\n timestamp: new Date().toISOString(),\n });\n});\n\n/**\n * 404 handler for unmatched routes.\n *\n * @param c - Hono context\n * @returns JSON error response with available routes\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/**\n * Exports the Hono app's fetch handler as the HTTP val entry point.\n *\n * This is the default export required by Val Town for HTTP vals.\n */\nexport default app.fetch;\n",[],[205,422],"93fab228-c417-11f0-97cd-42dde27851f2","cc70008c-c3e4-11f0-8120-42dde27851f2",["D",1763426599430],25,[],[205,435,33],"services","93deafec-c417-11f0-a9da-42dde27851f2","tsParser.ts","ccd3c522-c3e4-11f0-83ba-42dde27851f2",146,["D",1763426599231],"/**\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",[],[205,435,437],"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",[],[205,435,445],"93ebf56c-c417-11f0-ba79-42dde27851f2","docCache.ts","ccdfd38a-c3e4-11f0-a716-42dde27851f2",147,["D",1763426599175],"/**\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",[],[205,435,453],"cc6fffce-c3e4-11f0-8120-42dde27851f2",14,["D",1763404789828],[225,226,227,228],[205,435],"93d9635c-c417-11f0-870f-42dde27851f2","ui.ts","ccda4afa-c3e4-11f0-b160-42dde27851f2","cc62307e-c3e4-11f0-8120-42dde27851f2",145,["D",1763426599115],"/**\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",[],[205,474,466],"routes","93c05de4-c417-11f0-8d6b-42dde27851f2","apiDocs.ts","cccd7d52-c3e4-11f0-b9d5-42dde27851f2",143,["D",1763426599044],"/**\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",[],[205,474,476],"cc622fd4-c3e4-11f0-8120-42dde27851f2",13,["D",1763404789730],[222,223],[205,474],["D",1763404789463],[221,224,229],[205],["D",1763401318495],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":56,"_102":103,"_104":25},{"_13":87,"_32":88,"_44":43,"_89":45,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":46,"_96":97},"ctx",{"_80":-5,"_124":528,"_529":530,"_531":532,"_533":25,"_534":25,"_535":25,"_536":60,"_537":-5,"_538":-7,"_539":-7,"_540":64,"_541":25,"_542":25,"_543":-5,"_544":25,"_545":25,"_546":25,"_547":-5},"ENV",{"_499":500,"_501":502,"_503":88,"_504":505,"_506":507,"_508":509,"_510":511,"_512":513,"_514":515,"_516":517,"_518":519,"_520":521,"_522":523,"_524":525,"_526":527},"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 · v149