[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_491":492,"_493":494},"routes/_app.x.$handle.$name",{"_96":95,"_32":44,"_104":86,"_27":52,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":25,"_118":119,"_120":58,"_121":-5,"_122":-5,"_123":124},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_42":43,"_32":44,"_37":45,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":56,"_57":58,"_59":58,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":25},"version",128,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":20,"_34":36,"_37":38,"_39":14,"_40":41,"_24":25},"previous",{"_30":31,"_32":28,"_33":20,"_34":35},"deleted",false,"deletedHere","path","README.md","latestPath","fileId","ccebd50e-c3e4-11f0-b9d5-42dde27851f2","name","fileType","content","# Val Town Documentation Generator\n\nAutomatically generate beautiful, interactive documentation for your Val Town vals by parsing TypeScript AST and extracting functions, classes, interfaces, types, and constants with their JSDoc comments.\n\n## Features\n\n- 📝 **Automatic Code Parsing** - Extracts functions, classes, interfaces, type aliases, and constants\n- 💬 **JSDoc Support** - Parses `@param`, `@returns`, `@example`, and `@deprecated` tags\n- 🔍 **Search & Filter** - Quickly find what you're looking for\n- ⚡ **Fast Caching** - Sub-second responses for cached documentation (1-hour 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- `val` (required) - Val identifier in format `username/valname`\n- `refresh` (optional) - Set to `true` to bypass cache\n\n**Example:**\n```bash\ncurl \"https://your-val.val.town/api/docs?val=stevekrouse/example\"\n```\n\n**Response:**\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://your-val.val.town/?val=username/valname\n```\n\nThe UI provides:\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- 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://your-val.val.town/?val=stevekrouse/example\n ```\n\n### Deployment\n\nThis project is designed to run as a Val Town HTTP val. The entry point is `backend/docGenerator.http.ts`.\n\nTo deploy:\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:\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- [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.\n","# 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.","createdAt",["D",1763418115219],"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",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":54,"_100":101,"_102":25},"branch",{"_13":85,"_32":86,"_42":41,"_87":43,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":44,"_94":95},"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",{"_42":43,"_32":44,"_37":487,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":56,"_57":58,"_59":58,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":488,"_80":489,"_82":490,"_84":25},"tree",[215,225,242,244,245,246,247,248,249,250],"files",[215,216,217,218,219,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],"counts",{"_205":62,"_206":142,"_207":142,"_208":209,"_210":211},"contents",[125,126,127,128,129,130,131,132,133,134],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_42":199,"_32":200,"_30":201,"_138":-5,"_40":41,"_39":202,"_140":58,"_37":203,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_27":204},{"_42":193,"_32":194,"_30":195,"_138":-5,"_40":41,"_39":196,"_140":58,"_37":197,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_27":198},{"_42":186,"_32":187,"_30":188,"_138":-5,"_40":41,"_39":189,"_140":58,"_37":190,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_27":192},{"_42":179,"_32":180,"_30":181,"_138":-5,"_40":41,"_39":182,"_140":58,"_37":183,"_13":62,"_33":20,"_34":184,"_24":25,"_144":-5,"_27":185},{"_42":173,"_32":174,"_30":175,"_138":-5,"_40":41,"_39":160,"_140":58,"_37":176,"_13":62,"_33":20,"_34":177,"_24":25,"_144":-5,"_27":178},{"_42":170,"_32":28,"_30":31,"_138":-5,"_40":41,"_39":14,"_140":25,"_37":171,"_13":142,"_33":20,"_34":36,"_24":25,"_144":-5,"_27":172},{"_42":163,"_32":164,"_30":165,"_138":-5,"_40":41,"_39":166,"_140":25,"_37":167,"_13":142,"_33":20,"_34":168,"_24":25,"_144":-5,"_27":169},{"_42":155,"_32":156,"_30":157,"_138":-5,"_40":41,"_39":158,"_140":25,"_37":159,"_13":160,"_33":20,"_34":161,"_24":25,"_144":-5,"_27":162},{"_42":146,"_32":147,"_30":148,"_138":-5,"_40":41,"_39":149,"_140":25,"_37":150,"_13":151,"_33":152,"_34":153,"_24":25,"_144":-5,"_27":154},{"_42":135,"_32":136,"_30":137,"_138":-5,"_40":41,"_39":139,"_140":58,"_37":141,"_13":142,"_33":20,"_34":143,"_24":25,"_144":-5,"_27":145},"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",[136],"ab859064-c400-11f0-84ab-42dde27851f2","test.ts","0ee6d226-c3f7-11f0-be52-42dde27851f2",117,["D",1763416760432],38,"script","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);",[147],"07f190b6-c3ff-11f0-ae55-42dde27851f2","deno.json","cab598f4-c3dc-11f0-9928-42dde27851f2",95,["D",1763416056576],3,"{\n\t\"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n\t\"compilerOptions\": {\n\t\t\"lib\": [\n\t\t\t\"dom\",\n\t\t\t\"dom.iterable\",\n\t\t\t\"dom.asynciterable\",\n\t\t\t\"deno.ns\",\n\t\t\t\"deno.unstable\"\n\t\t],\n\t\t\"jsx\": \"react-jsx\",\n\t\t\"jsxImportSource\": \"https://esm.sh/react@18.2.0\",\n\t\t\"noImplicitAny\": false,\n\t\t\"strict\": false,\n\t\t\"types\": [\"https://www.val.town/types/valtown.d.ts\"]\n\t},\n\t\"experimental\": {\n\t\t\"unstable-node-globals\": true,\n\t\t\"unstable-sloppy-imports\": true,\n\t\t\"unstable-temporal\": true,\n\t\t\"unstable-worker-options\": true\n\t},\n\t\"imports\": {\n\t\t\"@biomejs/biome\": \"npm:@biomejs/biome@^2.3.6\",\n\t\t\"@valtown/sdk\": \"npm:@valtown/sdk@^0.36.0\"\n\t},\n\t\"lint\": {\n\t\t\"files\": {\n\t\t\t\"include\": [\"deno:/https/esm.town/**/*\"]\n\t\t},\n\t\t\"rules\": {\n\t\t\t\"exclude\": [\"no-explicit-any\", \"no-import-prefix\"]\n\t\t}\n\t},\n\t\"lock\": false,\n\t\"nodeModulesDir\": \"auto\"\n}\n",[156],"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",[164],"d2fdb60a-c403-11f0-9f4b-42dde27851f2",["D",1763418115219],[28],"cabf6d48-c3dc-11f0-8d89-42dde27851f2","AGENTS.md","cabf6dfc-c3dc-11f0-8d89-42dde27851f2",["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`",[174],"cac32640-c3dc-11f0-9928-42dde27851f2",".vtignore","cac3271c-c3dc-11f0-9928-42dde27851f2",4,["D",1763401351042],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor",[180],"cc47c946-c3e4-11f0-8a14-42dde27851f2","shared","cc47c9fa-c3e4-11f0-8a14-42dde27851f2",11,["D",1763404789566],"directory",[187],"cc29d652-c3e4-11f0-8a14-42dde27851f2","frontend","cc29d738-c3e4-11f0-8a14-42dde27851f2",9,["D",1763404789368],[194],"cc382342-c3e4-11f0-8a14-42dde27851f2","backend","cc382428-c3e4-11f0-8a14-42dde27851f2",10,["D",1763404789463],[200],"pulls","branches","forks","envVars",{"_212":142,"_214":62},"connections",{"_212":62,"_213":62},"count","unfilledCount","emptyCount",{"_42":199,"_32":200,"_30":201,"_138":-5,"_40":41,"_39":202,"_140":58,"_37":484,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_252":485,"_27":486},{"_42":479,"_32":470,"_30":464,"_138":201,"_40":41,"_39":480,"_140":58,"_37":481,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_252":482,"_27":483},{"_42":471,"_32":472,"_30":473,"_138":464,"_40":41,"_39":474,"_140":25,"_37":475,"_13":62,"_33":152,"_34":476,"_24":25,"_144":-5,"_252":477,"_27":478},{"_42":461,"_32":462,"_30":463,"_138":464,"_40":41,"_39":465,"_140":25,"_37":466,"_13":62,"_33":152,"_34":467,"_24":25,"_144":-5,"_252":468,"_27":469},{"_42":456,"_32":431,"_30":425,"_138":201,"_40":41,"_39":457,"_140":58,"_37":458,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_252":459,"_27":460},{"_42":448,"_32":449,"_30":450,"_138":425,"_40":41,"_39":451,"_140":25,"_37":452,"_13":62,"_33":152,"_34":453,"_24":25,"_144":-5,"_252":454,"_27":455},{"_42":440,"_32":441,"_30":442,"_138":425,"_40":41,"_39":443,"_140":25,"_37":444,"_13":62,"_33":152,"_34":445,"_24":25,"_144":-5,"_252":446,"_27":447},{"_42":432,"_32":433,"_30":434,"_138":425,"_40":41,"_39":435,"_140":25,"_37":436,"_13":196,"_33":152,"_34":437,"_24":25,"_144":-5,"_252":438,"_27":439},{"_42":422,"_32":423,"_30":424,"_138":425,"_40":41,"_39":426,"_140":25,"_37":427,"_13":329,"_33":152,"_34":428,"_24":25,"_144":-5,"_252":429,"_27":430},{"_42":414,"_32":415,"_30":56,"_138":201,"_40":41,"_39":416,"_140":25,"_37":417,"_13":62,"_33":418,"_34":419,"_24":25,"_144":44,"_252":420,"_27":421},{"_42":193,"_32":194,"_30":195,"_138":-5,"_40":41,"_39":196,"_140":58,"_37":411,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_252":412,"_27":413},{"_42":406,"_32":309,"_30":304,"_138":195,"_40":41,"_39":407,"_140":58,"_37":408,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_252":409,"_27":410},{"_42":398,"_32":399,"_30":400,"_138":304,"_40":41,"_39":401,"_140":25,"_37":402,"_13":182,"_33":152,"_34":403,"_24":25,"_144":-5,"_252":404,"_27":405},{"_42":390,"_32":391,"_30":392,"_138":304,"_40":41,"_39":393,"_140":25,"_37":394,"_13":62,"_33":152,"_34":395,"_24":25,"_144":-5,"_252":396,"_27":397},{"_42":382,"_32":383,"_30":384,"_138":304,"_40":41,"_39":385,"_140":25,"_37":386,"_13":62,"_33":152,"_34":387,"_24":25,"_144":-5,"_252":388,"_27":389},{"_42":374,"_32":375,"_30":376,"_138":304,"_40":41,"_39":377,"_140":25,"_37":378,"_13":62,"_33":152,"_34":379,"_24":25,"_144":-5,"_252":380,"_27":381},{"_42":366,"_32":367,"_30":368,"_138":304,"_40":41,"_39":369,"_140":25,"_37":370,"_13":142,"_33":152,"_34":371,"_24":25,"_144":-5,"_252":372,"_27":373},{"_42":358,"_32":359,"_30":360,"_138":304,"_40":41,"_39":361,"_140":25,"_37":362,"_13":62,"_33":152,"_34":363,"_24":25,"_144":-5,"_252":364,"_27":365},{"_42":350,"_32":351,"_30":352,"_138":304,"_40":41,"_39":353,"_140":25,"_37":354,"_13":62,"_33":152,"_34":355,"_24":25,"_144":-5,"_252":356,"_27":357},{"_42":342,"_32":343,"_30":344,"_138":304,"_40":41,"_39":345,"_140":25,"_37":346,"_13":142,"_33":152,"_34":347,"_24":25,"_144":-5,"_252":348,"_27":349},{"_42":334,"_32":335,"_30":336,"_138":304,"_40":41,"_39":337,"_140":25,"_37":338,"_13":62,"_33":152,"_34":339,"_24":25,"_144":-5,"_252":340,"_27":341},{"_42":326,"_32":327,"_30":328,"_138":304,"_40":41,"_39":329,"_140":25,"_37":330,"_13":62,"_33":152,"_34":331,"_24":25,"_144":-5,"_252":332,"_27":333},{"_42":318,"_32":319,"_30":320,"_138":304,"_40":41,"_39":321,"_140":25,"_37":322,"_13":62,"_33":152,"_34":323,"_24":25,"_144":-5,"_252":324,"_27":325},{"_42":310,"_32":311,"_30":312,"_138":304,"_40":41,"_39":313,"_140":25,"_37":314,"_13":160,"_33":152,"_34":315,"_24":25,"_144":-5,"_252":316,"_27":317},{"_42":301,"_32":302,"_30":303,"_138":304,"_40":41,"_39":151,"_140":25,"_37":305,"_13":62,"_33":152,"_34":306,"_24":25,"_144":-5,"_252":307,"_27":308},{"_42":293,"_32":294,"_30":295,"_138":195,"_40":41,"_39":296,"_140":58,"_37":297,"_13":278,"_33":20,"_34":298,"_24":25,"_144":-5,"_252":299,"_27":300},{"_42":285,"_32":286,"_30":287,"_138":195,"_40":41,"_39":288,"_140":25,"_37":289,"_13":62,"_33":152,"_34":290,"_24":25,"_144":-5,"_252":291,"_27":292},{"_42":186,"_32":187,"_30":188,"_138":-5,"_40":41,"_39":189,"_140":58,"_37":282,"_13":62,"_33":191,"_34":-5,"_24":25,"_144":-5,"_252":283,"_27":284},{"_42":273,"_32":274,"_30":275,"_138":188,"_40":41,"_39":276,"_140":25,"_37":277,"_13":278,"_33":152,"_34":279,"_24":25,"_144":-5,"_252":280,"_27":281},{"_42":179,"_32":180,"_30":181,"_138":-5,"_40":41,"_39":182,"_140":58,"_37":270,"_13":62,"_33":20,"_34":184,"_24":25,"_144":-5,"_252":271,"_27":272},{"_42":173,"_32":174,"_30":175,"_138":-5,"_40":41,"_39":160,"_140":58,"_37":267,"_13":62,"_33":20,"_34":177,"_24":25,"_144":-5,"_252":268,"_27":269},{"_42":170,"_32":28,"_30":31,"_138":-5,"_40":41,"_39":14,"_140":25,"_37":264,"_13":142,"_33":20,"_34":36,"_24":25,"_144":-5,"_252":265,"_27":266},{"_42":163,"_32":164,"_30":165,"_138":-5,"_40":41,"_39":166,"_140":25,"_37":261,"_13":142,"_33":20,"_34":168,"_24":25,"_144":-5,"_252":262,"_27":263},{"_42":155,"_32":156,"_30":157,"_138":-5,"_40":41,"_39":158,"_140":25,"_37":258,"_13":160,"_33":20,"_34":161,"_24":25,"_144":-5,"_252":259,"_27":260},{"_42":146,"_32":147,"_30":148,"_138":-5,"_40":41,"_39":149,"_140":25,"_37":255,"_13":151,"_33":152,"_34":153,"_24":25,"_144":-5,"_252":256,"_27":257},{"_42":135,"_32":136,"_30":137,"_138":-5,"_40":41,"_39":139,"_140":58,"_37":251,"_13":142,"_33":20,"_34":143,"_24":25,"_144":-5,"_252":253,"_27":254},["D",1763402806837],"children",[],[136],["D",1763416760432],[],[147],["D",1763416056576],[],[156],["D",1763411215215],[],[164],["D",1763418115219],[],[28],["D",1763401351018],[],[174],["D",1763401351042],[],[180],"48173480-c403-11f0-9f4b-42dde27851f2","docTypes.ts","cce74336-c3e4-11f0-b160-42dde27851f2",127,["D",1763417882183],2,"import ValTown from \"npm:@valtown/sdk@latest\";\n\nconst client = new ValTown();\ntype Val = Awaited>;\n\n/**\n * Shared documentation types for Val Town documentation generator\n * These types form the contract between the backend parser and frontend UI\n */\n\n/**\n * JSDoc-style comment information\n */\nexport interface DocComment {\n /** Raw comment text */\n raw: string;\n /** Parsed description */\n description: string;\n /** @param tags */\n params?: Array<{ name: string; type?: string; description: string }>;\n /** @returns tag */\n returns?: { type?: string; description: string };\n /** @example tags */\n examples?: string[];\n /** @deprecated tag */\n deprecated?: string;\n /** Other tags */\n tags?: Array<{ name: string; value: string }>;\n}\n\n/**\n * Parameter information for functions and methods\n */\nexport interface ParameterDoc {\n name: string;\n type: string;\n optional: boolean;\n defaultValue?: string;\n description?: string;\n}\n\n/**\n * Function or method documentation\n */\nexport interface FunctionDoc {\n kind: \"function\";\n name: string;\n signature: string;\n parameters: ParameterDoc[];\n returnType: string;\n isAsync: boolean;\n isExported: boolean;\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Class property documentation\n */\nexport interface PropertyDoc {\n name: string;\n type: string;\n isReadonly: boolean;\n isOptional: boolean;\n visibility: \"public\" | \"private\" | \"protected\";\n comment?: DocComment;\n}\n\n/**\n * Class method documentation\n */\nexport interface MethodDoc {\n name: string;\n signature: string;\n parameters: ParameterDoc[];\n returnType: string;\n isAsync: boolean;\n isStatic: boolean;\n visibility: \"public\" | \"private\" | \"protected\";\n comment?: DocComment;\n}\n\n/**\n * Class documentation\n */\nexport interface ClassDoc {\n kind: \"class\";\n name: string;\n isExported: boolean;\n isAbstract: boolean;\n extends?: string;\n implements?: string[];\n properties: PropertyDoc[];\n methods: MethodDoc[];\n constructor?: {\n parameters: ParameterDoc[];\n comment?: DocComment;\n };\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Interface property documentation\n */\nexport interface InterfacePropertyDoc {\n name: string;\n type: string;\n isOptional: boolean;\n isReadonly: boolean;\n comment?: DocComment;\n}\n\n/**\n * Interface method documentation\n */\nexport interface InterfaceMethodDoc {\n name: string;\n signature: string;\n parameters: ParameterDoc[];\n returnType: string;\n comment?: DocComment;\n}\n\n/**\n * Interface documentation\n */\nexport interface InterfaceDoc {\n kind: \"interface\";\n name: string;\n isExported: boolean;\n extends?: string[];\n properties: InterfacePropertyDoc[];\n methods: InterfaceMethodDoc[];\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Type alias documentation\n */\nexport interface TypeAliasDoc {\n kind: \"type\";\n name: string;\n type: string;\n isExported: boolean;\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Constant/variable documentation\n */\nexport interface ConstantDoc {\n kind: \"constant\";\n name: string;\n type: string;\n value?: string;\n isExported: boolean;\n comment?: DocComment;\n location: { line: number; file: string };\n}\n\n/**\n * Import statement information\n */\nexport interface ImportInfo {\n source: string;\n imports: Array<{\n name: string;\n alias?: string;\n isDefault?: boolean;\n isNamespace?: boolean;\n }>;\n location: { line: number; file: string };\n}\n\n/**\n * Val metadata from Val Town API\n */\nexport interface ValMetadata {\n id: string;\n 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 value is a DocManifest\n */\nexport function isDocManifest(value: unknown): value is DocManifest {\n if (!value || typeof value !== \"object\") return false;\n const obj = value as Record;\n\n return (\n typeof obj.val === \"string\" &&\n typeof obj.version === \"string\" &&\n typeof obj.generatedAt === \"string\" &&\n typeof obj.exports === \"object\" &&\n obj.exports !== null &&\n Array.isArray((obj.exports as Record).functions) &&\n Array.isArray((obj.exports as Record).classes) &&\n Array.isArray((obj.exports as Record).interfaces) &&\n Array.isArray((obj.exports as Record).types) &&\n Array.isArray((obj.exports as Record).constants) &&\n Array.isArray(obj.imports) &&\n typeof obj.metadata === \"object\" &&\n obj.metadata !== null\n );\n}\n\n/**\n * Runtime validation that throws if value is not a DocManifest\n */\nexport function assertDocManifest(data: unknown): asserts data is DocManifest {\n if (!isDocManifest(data)) {\n throw new Error(\"Invalid DocManifest structure\");\n }\n}\n\n/**\n * Creates an empty DocManifest template\n */\nexport function createEmptyManifest(\n val: string,\n version: string,\n metadata: ValMetadata,\n): DocManifest {\n return {\n val,\n version,\n generatedAt: new Date().toISOString(),\n exports: {\n functions: [],\n classes: [],\n interfaces: [],\n types: [],\n constants: [],\n },\n imports: [],\n metadata,\n };\n}",[],[187,274],["D",1763404789566],[243],[187],"cc81206a-c3e4-11f0-8120-42dde27851f2","index.tsx","cc81213c-c3e4-11f0-8120-42dde27851f2",15,["D",1763404789941],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\n\nimport React from \"https://esm.sh/react@18.2.0\";\nimport { createRoot } from \"https://esm.sh/react-dom@18.2.0/client\";\nimport { App } from \"./components/App.tsx\";\n\n// Get initial data injected by server\nconst initialData = (window as any).__INITIAL_DATA__ || {};\n\nconst root = createRoot(document.getElementById(\"root\")!);\nroot.render(\n \n \n \n);\n",[],[194,286],"a03dd340-c3f3-11f0-bbb3-42dde27851f2","index.html","cc8da1a0-c3e4-11f0-85f8-42dde27851f2",42,["D",1763411158044],"\n\n\n \n \n Val Town Documentation Generator\n\n \n \n\n \n \n\n \n\n\n

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

\n type {type.name}\n

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

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

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

Definition

\n \n

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

\n Val Info\n

{manifest.val}

v{manifest.version}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

\n )}\n

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

\n {manifest.metadata.name}\n

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

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

{manifest.metadata.readme}

\n )}\n

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

No results found for \"{searchQuery}\"

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

Functions

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

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

Classes

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

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

Interfaces

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

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

Type Aliases

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

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

Constants

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

\n )}\n

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

Generating documentation...

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

\n interface {iface.name}\n

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

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

\n )}\n

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

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

Properties

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

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

\n {prop.comment && (\n

\n {prop.comment.description}\n

\n )}\n

\n ))}\n

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

Methods

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

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

\n {method.comment && (\n

\n {method.comment.description}\n

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

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

\n )}\n

\n ))}\n

\n )}\n

\n );\n}\n",[],[194,309,335],"07fdd4f2-c3ff-11f0-b72a-42dde27851f2","Header.tsx","ccba8936-c3e4-11f0-b9d5-42dde27851f2",97,["D",1763416056577],"/** @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\nexport interface HeaderProps {\n\tonSubmit: (val: string) => void;\n\tonRefresh: () => void;\n\tcurrentVal: string;\n\tonSearchChange: (query: string) => void;\n}\n\nexport function Header(props: HeaderProps): React.ReactElement {\n\tconst [inputVal, setInputVal] = useState(props.currentVal);\n\n\tconst handleSubmit = (e: React.FormEvent) => {\n\t\te.preventDefault();\n\t\tif (inputVal.trim()) {\n\t\t\tprops.onSubmit(inputVal.trim());\n\t\t}\n\t};\n\n\treturn (\n\t\t

\n\t\t\t

\n\t\t\t\t

\n\t\t\t\t\t

\n\t\t\t\t\t\t

\n\t\t\t\t\t\t\t📚 Val Town Docs\n\t\t\t\t\t\t

\n\t\t\t\t\t

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

\n\n\t\t\t\t

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

\n\t\t\t

\n\t\t

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

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

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

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

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

Signature

\n \n

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

Parameters

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

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

\n )}\n\n

Returns

\n {func.returnType}\n

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

\n ❌\n

Error

{props.message}

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

\n {constant.name}\n

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

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

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

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

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

Value

\n \n

\n )}\n

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

\n      {props.code}\n

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

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

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

\n extends {cls.extends}\n

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

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

\n )}\n

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

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

Constructor

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

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

\n )}\n

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

Properties

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

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

\n {prop.comment && (\n

\n {prop.comment.description}\n

\n )}\n

\n ))}\n

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

Methods

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

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

\n {method.comment && (\n

\n {method.comment.description}\n

\n )}\n

\n ))}\n

\n )}\n

\n );\n}\n",[],[194,309,391],"6974aa94-c3ff-11f0-b399-42dde27851f2","App.tsx","cc86876c-c3e4-11f0-83ba-42dde27851f2",103,["D",1763416220160],"/** @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\nexport interface AppProps {\n\tinitialManifest?: DocManifest;\n\tinitialVal?: string;\n\terror?: string;\n}\n\nexport function App(props: AppProps): React.ReactElement {\n\tconst [manifest, setManifest] = useState(\n\t\tprops.initialManifest || null,\n\t);\n\tconst [val, setVal] = useState(props.initialVal || \"\");\n\tconst [loading, setLoading] = useState(false);\n\tconst [error, setError] = useState(props.error || null);\n\tconst [searchQuery, setSearchQuery] = useState(\"\");\n\n\t// Fetch documentation for a val\n\tconst fetchDocs = async (valIdentifier: string, refresh = false) => {\n\t\tif (!valIdentifier) return;\n\n\t\tconsole.log(\n\t\t\t`[fetchDocs] Requesting docs for val: ${valIdentifier}, refresh: ${refresh}`,\n\t\t);\n\t\tsetLoading(true);\n\t\tsetError(null);\n\n\t\ttry {\n\t\t\tconst url = `/api/docs?val=${encodeURIComponent(valIdentifier)}${\n\t\t\t\trefresh ? \"&refresh=true\" : \"\"\n\t\t\t}`;\n\t\t\tconsole.log(`[fetchDocs] Fetching from URL: ${url}`);\n\n\t\t\tconst response = await fetch(url);\n\t\t\tconsole.log(\n\t\t\t\t`[fetchDocs] Response status: ${response.status} ${response.statusText}`,\n\t\t\t);\n\n\t\t\tif (!response.ok) {\n\t\t\t\tconst errorData = await response.json();\n\t\t\t\tconsole.error(`[fetchDocs] Error response:`, errorData);\n\t\t\t\tthrow new Error(errorData.message || \"Failed to fetch documentation\");\n\t\t\t}\n\n\t\t\tconst data = await response.json();\n\t\t\tconsole.log(`[fetchDocs] Successfully fetched docs:`, data);\n\t\t\tsetManifest(data);\n\t\t\tsetVal(valIdentifier);\n\n\t\t\t// Update URL without reload\n\t\t\tconst newUrl = `/?val=${encodeURIComponent(valIdentifier)}`;\n\t\t\twindow.history.pushState({}, \"\", newUrl);\n\t\t} catch (err) {\n\t\t\tconsole.error(`[fetchDocs] Error caught:`, err);\n\t\t\tsetError(err instanceof Error ? err.message : \"Unknown error\");\n\t\t\tsetManifest(null);\n\t\t} finally {\n\t\t\tsetLoading(false);\n\t\t}\n\t};\n\n\t// Handle val input submission\n\tconst handleSubmit = (valIdentifier: string) => {\n\t\tfetchDocs(valIdentifier, false);\n\t};\n\n\t// Handle refresh\n\tconst handleRefresh = () => {\n\t\tif (val) {\n\t\t\tfetchDocs(val, true);\n\t\t}\n\t};\n\n\treturn (\n\t\t

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

\n\t\t\t\t\t\n\t\t\t\t

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

\n\t\t\t\t\t\n\t\t\t\t

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

\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t

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

\n\t\t\t\t\t

\n\t\t\t\t\t\tVal Town Documentation Generator\n\t\t\t\t\t

\n\t\t\t\t\t

\n\t\t\t\t\t\tEnter a val identifier (e.g., \"username/valname\") above to generate\n\t\t\t\t\t\tdocumentation\n\t\t\t\t\t

\n\t\t\t\t\t

\n\t\t\t\t\t\t

Features

\n\t\t\t\t\t\t

\n\t\t\t\t\t\t\t\t📝\n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tAutomatic extraction of functions, classes, interfaces, types,\n\t\t\t\t\t\t\t\t\tand constants\n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t
\n\t\t\t\t\t\t\t\t💬\n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t\tJSDoc comment parsing with @param, @returns, and @example tags\n\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t
\n\t\t\t\t\t\t\t\t🔍\n\t\t\t\t\t\t\t\tSearch and filter functionality\n\t\t\t\t\t\t\t
\n\t\t\t\t\t\t\t\t⚡\n\t\t\t\t\t\t\t\tFast caching for quick subsequent loads\n\t\t\t\t\t\t\t
\n\t\t\t\t\t\t\t\t🎨\n\t\t\t\t\t\t\t\tClean, responsive UI with syntax highlighting\n\t\t\t\t\t\t\t

\n\t\t\t\t\t

\n\t\t\t\t

\n\t\t\t)}\n\t\t

\n\t);\n}\n",[],[194,309,399],"cc53b27e-c3e4-11f0-8a14-42dde27851f2",12,["D",1763404789643],[227,228,229,230,231,232,233,234,235,236,237,238,239],[194,309],["D",1763404789368],[226,240,241],[194],"ccc2aff8-c3e4-11f0-b160-42dde27851f2","docGenerator.http.ts",28,["D",1763404790370],"http","/**\n * Val Town Documentation Generator\n * Main HTTP val entry point\n *\n * Provides:\n * - GET / - Documentation viewer UI\n * - GET /api/docs?val=username/valname - JSON API for documentation\n * - GET /frontend/* - Static frontend assets\n * - GET /shared/* - Shared module assets\n */\n\nimport { Hono } from \"npm:hono@4.0.0\";\nimport { serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport { getApiDocs } from \"./routes/apiDocs.ts\";\nimport { getUI } from \"./routes/ui.ts\";\n\nconst app = new Hono();\n\n// Unwrap Hono errors to see original error details\napp.onError((err, c) => {\n throw err;\n});\n\n/**\n * API Routes\n */\napp.get(\"/api/docs\", getApiDocs);\n\n/**\n * UI Routes\n */\napp.get(\"/\", getUI);\n\n/**\n * Static File Serving\n */\napp.get(\"/frontend/*\", (c) => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", (c) => serveFile(c.req.path, import.meta.url));\n\n/**\n * Health check endpoint\n */\napp.get(\"/health\", (c) => {\n return c.json({\n status: \"ok\",\n timestamp: new Date().toISOString(),\n });\n});\n\n/**\n * 404 handler\n */\napp.notFound((c) => {\n return c.json(\n {\n error: \"NOT_FOUND\",\n message: \"Route not found\",\n availableRoutes: [\n \"GET /\",\n \"GET /api/docs?val=username/valname\",\n \"GET /health\",\n ],\n },\n 404,\n );\n});\n\n// Export the Hono app as the HTTP val entry point\nexport default app.fetch;\n",[],[200,415],"ab79877e-c400-11f0-bd82-42dde27851f2","valFetcher.ts","ccdc741a-c3e4-11f0-b1eb-42dde27851f2","cc70008c-c3e4-11f0-8120-42dde27851f2",115,["D",1763416760432],"/**\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",[],[200,431,423],"services","2bdff34c-c403-11f0-b037-42dde27851f2","tsParser.ts","ccd3c522-c3e4-11f0-83ba-42dde27851f2",126,["D",1763417834844],"/**\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 * Parse JSDoc comment from a node\n */\nfunction parseJSDocComment(\n node: ts.Node,\n sourceFile: ts.SourceFile,\n): DocComment | undefined {\n const jsDocTags = ts.getJSDocTags(node);\n const jsDocComments = (node as { jsDoc?: ts.JSDoc[] }).jsDoc;\n\n if (!jsDocComments || jsDocComments.length === 0) {\n return undefined;\n }\n\n const comment = jsDocComments[0];\n const commentText = comment.comment;\n const description = 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 = 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 * Get type as string from type node\n */\nfunction getTypeString(\n typeNode: ts.TypeNode | undefined,\n _checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): string {\n if (!typeNode) return \"any\";\n return typeNode.getText(sourceFile);\n}\n\n/**\n * Parse parameter documentation\n */\nfunction parseParameters(\n parameters: ts.NodeArray,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): ParameterDoc[] {\n return parameters.map((param) => {\n const name = param.name.getText(sourceFile);\n const type = getTypeString(param.type, checker, sourceFile);\n const optional = !!param.questionToken || !!param.initializer;\n const defaultValue = param.initializer?.getText(sourceFile);\n\n return {\n name,\n type,\n optional,\n defaultValue,\n };\n });\n}\n\n/**\n * Parse function declaration or expression\n */\nfunction parseFunctionDeclaration(\n node: ts.FunctionDeclaration | ts.VariableStatement,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): FunctionDoc | null {\n let funcDecl:\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 = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line +\n 1;\n\n return {\n kind: \"function\",\n name,\n signature,\n parameters,\n returnType,\n isAsync,\n isExported,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse class property\n */\nfunction parseProperty(\n node: ts.PropertyDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): PropertyDoc {\n const name = node.name.getText(sourceFile);\n const type = getTypeString(node.type, checker, sourceFile);\n const isReadonly = !!node.modifiers?.some(\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 * Parse class method\n */\nfunction parseMethod(\n node: ts.MethodDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): MethodDoc {\n const name = node.name.getText(sourceFile);\n const signature = node.getText(sourceFile);\n const parameters = parseParameters(node.parameters, checker, sourceFile);\n const returnType = getTypeString(node.type, checker, sourceFile);\n const isAsync = !!node.modifiers?.some(\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 * Parse class declaration\n */\nfunction parseClassDeclaration(\n node: ts.ClassDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): ClassDoc | null {\n const name = node.name?.getText(sourceFile);\n if (!name) return null;\n\n const isExported = !!node.modifiers?.some(\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 = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line +\n 1;\n\n return {\n kind: \"class\",\n name,\n isExported,\n isAbstract,\n extends: extendsType,\n implements: implementsTypes,\n properties,\n methods,\n constructor,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse interface property\n */\nfunction parseInterfaceProperty(\n node: ts.PropertySignature,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): InterfacePropertyDoc {\n const name = node.name.getText(sourceFile);\n const type = getTypeString(node.type, checker, sourceFile);\n const isOptional = !!node.questionToken;\n const isReadonly = !!node.modifiers?.some(\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 * Parse interface method\n */\nfunction parseInterfaceMethod(\n node: ts.MethodSignature,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): InterfaceMethodDoc {\n const name = node.name.getText(sourceFile);\n const signature = node.getText(sourceFile);\n const parameters = parseParameters(node.parameters, checker, sourceFile);\n const returnType = getTypeString(node.type, checker, sourceFile);\n const comment = parseJSDocComment(node, sourceFile);\n\n return {\n name,\n signature,\n parameters,\n returnType,\n comment,\n };\n}\n\n/**\n * Parse interface declaration\n */\nfunction parseInterfaceDeclaration(\n node: ts.InterfaceDeclaration,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): InterfaceDoc {\n const name = node.name.getText(sourceFile);\n const isExported = !!node.modifiers?.some(\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 = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line +\n 1;\n\n return {\n kind: \"interface\",\n name,\n isExported,\n extends: extendsTypes,\n properties,\n methods,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse type alias declaration\n */\nfunction parseTypeAliasDeclaration(\n node: ts.TypeAliasDeclaration,\n _checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): TypeAliasDoc {\n const name = node.name.getText(sourceFile);\n const type = node.type.getText(sourceFile);\n const isExported = !!node.modifiers?.some(\n (m) => m.kind === ts.SyntaxKind.ExportKeyword,\n );\n const comment = parseJSDocComment(node, sourceFile);\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line +\n 1;\n\n return {\n kind: \"type\",\n name,\n type,\n isExported,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse constant/variable declaration\n */\nfunction parseConstantDeclaration(\n node: ts.VariableStatement,\n checker: ts.TypeChecker,\n sourceFile: ts.SourceFile,\n): ConstantDoc | null {\n const declaration = node.declarationList.declarations[0];\n if (!declaration) return null;\n\n // Skip if this is actually a function (handled elsewhere)\n if (\n declaration.initializer &&\n (ts.isArrowFunction(declaration.initializer) ||\n ts.isFunctionExpression(declaration.initializer))\n ) {\n return null;\n }\n\n const name = declaration.name.getText(sourceFile);\n const type = declaration.type\n ? getTypeString(declaration.type, checker, sourceFile)\n : checker.typeToString(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 = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line +\n 1;\n\n return {\n kind: \"constant\",\n name,\n type,\n value,\n isExported,\n comment,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse import declaration\n */\nfunction parseImportDeclaration(\n node: ts.ImportDeclaration,\n sourceFile: ts.SourceFile,\n): ImportInfo {\n const source = (node.moduleSpecifier as ts.StringLiteral).text;\n const imports: ImportInfo[\"imports\"] = [];\n\n if (node.importClause) {\n // Default import\n if (node.importClause.name) {\n imports.push({\n name: node.importClause.name.getText(sourceFile),\n isDefault: true,\n });\n }\n\n // Named imports\n if (node.importClause.namedBindings) {\n if (ts.isNamespaceImport(node.importClause.namedBindings)) {\n // import * as foo\n imports.push({\n name: node.importClause.namedBindings.name.getText(sourceFile),\n isNamespace: true,\n });\n } else if (ts.isNamedImports(node.importClause.namedBindings)) {\n // import { a, b as c }\n for (const element of node.importClause.namedBindings.elements) {\n imports.push({\n name: element.name.getText(sourceFile),\n alias: element.propertyName?.getText(sourceFile),\n });\n }\n }\n }\n }\n\n const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line +\n 1;\n\n return {\n source,\n imports,\n location: { line, file: sourceFile.fileName },\n };\n}\n\n/**\n * Parse a Val bundle and extract documentation\n */\nexport function parseValBundle(bundle: ValBundle): DocManifest {\n const manifest = createEmptyManifest(\n `${bundle.metadata.author.username}/${bundle.metadata.name}`,\n new Date().toISOString(), // 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}",[],[200,431,433],"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",[],[200,431,441],"ccdfd2d6-c3e4-11f0-a716-42dde27851f2","docCache.ts","ccdfd38a-c3e4-11f0-a716-42dde27851f2",34,["D",1763404790530],"/**\n * Documentation cache using Val Town blob storage with in-memory front cache\n */\n\nimport { blob } from \"https://esm.town/v/std/blob\";\n\n/**\n * Cache entry metadata\n */\nexport interface CacheEntry {\n data: T;\n version: string;\n cachedAt: number;\n expiresAt: number;\n}\n\n/**\n * Cache configuration\n */\nexport interface CacheConfig {\n /** Cache TTL in milliseconds (default: 1 hour) */\n ttlMs?: number;\n /** Blob key prefix (default: \"doc-cache\") */\n blobPrefix?: string;\n}\n\n/**\n * Documentation cache interface\n */\nexport interface DocCache {\n get(key: string): Promise;\n set(key: string, data: T, metadata: { version: string }): Promise;\n has(key: string): Promise;\n isExpired(key: string): Promise;\n delete(key: string): Promise;\n clear(): Promise;\n}\n\n/**\n * In-memory cache with LRU eviction\n */\nclass MemoryCache {\n private cache = new Map>();\n private readonly maxSize: number;\n\n constructor(maxSize = 100) {\n this.maxSize = maxSize;\n }\n\n get(key: string): CacheEntry | null {\n const entry = this.cache.get(key) as CacheEntry | undefined;\n if (!entry) return null;\n\n // Move to end (most recently used)\n this.cache.delete(key);\n this.cache.set(key, entry);\n\n return entry;\n }\n\n set(key: string, entry: CacheEntry): void {\n // Remove if exists (to update position)\n if (this.cache.has(key)) {\n this.cache.delete(key);\n }\n\n // Evict oldest if at capacity\n if (this.cache.size >= this.maxSize) {\n const firstKey = this.cache.keys().next().value;\n if (firstKey !== undefined) {\n this.cache.delete(firstKey);\n }\n }\n\n this.cache.set(key, entry);\n }\n\n has(key: string): boolean {\n return this.cache.has(key);\n }\n\n delete(key: string): void {\n this.cache.delete(key);\n }\n\n clear(): void {\n this.cache.clear();\n }\n}\n\n/**\n * Create a documentation cache instance\n */\nexport function createDocCache(config: CacheConfig = {}): DocCache {\n const ttlMs = config.ttlMs ?? 60 * 60 * 1000; // 1 hour default\n const blobPrefix = config.blobPrefix ?? \"doc-cache\";\n const memoryCache = new MemoryCache(100);\n\n function deriveBlobKey(key: string): string {\n return `${blobPrefix}:${key}`;\n }\n\n return {\n async get(key: string): Promise {\n const now = Date.now();\n\n // Check memory cache first\n const memEntry = memoryCache.get(key);\n if (memEntry && memEntry.expiresAt > now) {\n return memEntry.data;\n }\n\n // Fall back to blob storage\n const blobKey = deriveBlobKey(key);\n const blobEntry = await blob.getJSON(blobKey) as CacheEntry | null;\n\n if (!blobEntry) {\n return null;\n }\n\n // Check if expired\n if (blobEntry.expiresAt <= now) {\n // Clean up expired entry\n await blob.delete(blobKey);\n memoryCache.delete(key);\n return null;\n }\n\n // Populate memory cache\n memoryCache.set(key, blobEntry);\n\n return blobEntry.data;\n },\n\n async set(\n key: string,\n data: T,\n metadata: { version: string },\n ): Promise {\n const now = Date.now();\n const entry: CacheEntry = {\n data,\n version: metadata.version,\n cachedAt: now,\n expiresAt: now + ttlMs,\n };\n\n // Store in both memory and blob\n memoryCache.set(key, entry);\n await blob.setJSON(deriveBlobKey(key), entry);\n },\n\n async has(key: string): Promise {\n // Check memory first\n if (memoryCache.has(key)) {\n const entry = memoryCache.get(key);\n if (entry && entry.expiresAt > Date.now()) {\n return true;\n }\n }\n\n // Check blob\n const blobKey = deriveBlobKey(key);\n const blobEntry = await blob.getJSON(blobKey) as CacheEntry |\n null;\n\n if (!blobEntry) {\n return false;\n }\n\n return blobEntry.expiresAt > Date.now();\n },\n\n async isExpired(key: string): Promise {\n const hasKey = await this.has(key);\n return !hasKey;\n },\n\n async delete(key: string): Promise {\n memoryCache.delete(key);\n await blob.delete(deriveBlobKey(key));\n },\n\n async clear(): Promise {\n memoryCache.clear();\n // List and delete all blob entries with our prefix\n const keys = await blob.list(blobPrefix);\n await Promise.all(keys.map((key) => blob.delete(key)));\n },\n };\n}\n\n/**\n * Derive cache key from val identifier and version\n */\nexport function deriveCacheKey(val: string, version?: string): string {\n const normalized = val.toLowerCase().replace(/[^a-z0-9_/-]/g, \"_\");\n return version ? `${normalized}@${version}` : normalized;\n}\n\n/**\n * Default doc cache instance with 1 hour TTL\n */\nexport const docCache = createDocCache({\n ttlMs: 60 * 60 * 1000,\n blobPrefix: \"doc-manifest\",\n});\n",[],[200,431,449],"cc6fffce-c3e4-11f0-8120-42dde27851f2",14,["D",1763404789828],[220,221,222,223],[200,431],"ccda4a1e-c3e4-11f0-b160-42dde27851f2","ui.ts","ccda4afa-c3e4-11f0-b160-42dde27851f2","cc62307e-c3e4-11f0-8120-42dde27851f2",32,["D",1763404790450],"/**\n * UI routes for serving the documentation viewer\n */\n\nimport type { Context } from \"npm:hono@4.0.0\";\nimport { readFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport { generateDocs, updateCachedHtml } from \"../services/docService.ts\";\n\n/**\n * Render the HTML page with optional initial data\n */\nasync function renderIndexPage(data: {\n manifest?: unknown;\n val?: string;\n error?: string;\n}): Promise {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n\n // Inject initial data to avoid extra round-trips\n const dataScript = ``;\n\n html = html.replace(\"\", `${dataScript}`);\n\n return html;\n}\n\n/**\n * GET /\n * Serves the documentation viewer UI\n */\nexport async function getUI(c: Context) {\n const initialVal = c.req.query(\"val\");\n\n // If no val specified, show empty UI\n if (!initialVal) {\n const html = await renderIndexPage({});\n return c.html(html);\n }\n\n try {\n // Try to get cached docs\n const cached = await generateDocs(initialVal, { refresh: false });\n\n // Check if we have cached SSR HTML\n if (cached.ssrHtml) {\n return c.html(cached.ssrHtml);\n }\n\n // Generate HTML with initial manifest\n const html = await renderIndexPage({\n manifest: cached.manifest,\n val: initialVal,\n });\n\n // Cache the HTML for next time\n await updateCachedHtml(initialVal, html);\n\n return c.html(html);\n } catch (error) {\n console.error(\"[ui] Error loading docs:\", error);\n\n // Return UI with error message\n const html = await renderIndexPage({\n val: initialVal,\n error: error instanceof Error ? error.message : \"Unknown error\",\n });\n\n return c.html(html);\n }\n}\n",[],[200,470,462],"routes","cccd7cb2-c3e4-11f0-b9d5-42dde27851f2","apiDocs.ts","cccd7d52-c3e4-11f0-b9d5-42dde27851f2",30,["D",1763404790430],"/**\n * API routes for documentation generation\n */\n\nimport type { Context } from \"npm:hono@4.0.0\";\nimport { generateDocs } from \"../services/docService.ts\";\n\n/**\n * GET /api/docs\n * Returns documentation manifest as JSON\n */\nexport async function getApiDocs(c: Context) {\n const val = c.req.query(\"val\");\n\n if (!val) {\n return c.json(\n {\n error: \"BAD_REQUEST\",\n message: 'Missing required query parameter \"val\"',\n example: \"/api/docs?val=username/valname\",\n },\n 400,\n );\n }\n\n try {\n const refresh = c.req.query(\"refresh\") === \"true\";\n const { manifest } = await generateDocs(val, { refresh });\n\n return c.json(manifest);\n } catch (error) {\n console.error(\"[api-docs] Error generating docs:\", error);\n\n if (error instanceof Error) {\n // Handle specific error types\n if (error.message.includes(\"not found\")) {\n return c.json(\n {\n error: \"NOT_FOUND\",\n message: error.message,\n },\n 404,\n );\n }\n\n if (error.message.includes(\"Invalid val identifier\")) {\n return c.json(\n {\n error: \"BAD_REQUEST\",\n message: error.message,\n },\n 400,\n );\n }\n\n return c.json(\n {\n error: \"INTERNAL_ERROR\",\n message: error.message,\n },\n 500,\n );\n }\n\n return c.json(\n {\n error: \"INTERNAL_ERROR\",\n message: \"An unexpected error occurred\",\n },\n 500,\n );\n }\n}\n",[],[200,470,472],"cc622fd4-c3e4-11f0-8120-42dde27851f2",13,["D",1763404789730],[217,218],[200,470],["D",1763404789463],[216,219,224],[200],["D",1763401318495],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":54,"_100":101,"_102":25},{"_13":85,"_32":86,"_42":41,"_87":43,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":44,"_94":95},"ctx",{"_78":-5,"_122":524,"_525":526,"_527":528,"_529":25,"_530":25,"_531":25,"_532":58,"_533":-5,"_534":-7,"_535":-7,"_536":62,"_537":25,"_538":25,"_539":-5,"_540":25,"_541":25,"_542":25,"_543":-5},"ENV",{"_495":496,"_497":498,"_499":86,"_500":501,"_502":503,"_504":505,"_506":507,"_508":509,"_510":511,"_512":513,"_514":515,"_516":517,"_518":519,"_520":521,"_522":523},"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 · v128