`\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- **Environment Variables:** Use `Deno.env.get('keyname')` with defensive checks:\n ```ts\n const apiKey = Deno.env.get(\"API_KEY\");\n if (!apiKey) {\n throw new Error(\"API_KEY not configured\");\n }\n ```\n Generally prefer APIs that don't require keys when possible.\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### Error Handling\n\nFor HTTP vals, handle errors gracefully and return appropriate status codes:\n\n```ts\nexport default async function (req: Request): Promise {\n try {\n // Your logic here\n return new Response(\"Success\");\n } catch (error) {\n return new Response(`Error: ${error.message}`, { status: 500 });\n }\n}\n```\n\nFor non-HTTP vals, let errors bubble up with full context rather than catching\nand merely logging them.\n\n### CORS Headers\n\nWhen building APIs consumed by browsers, include CORS headers:\n\n```ts\nreturn new Response(JSON.stringify(data), {\n headers: {\n \"Content-Type\": \"application/json\",\n \"Access-Control-Allow-Origin\": \"*\",\n },\n});\n```\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\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\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`\n\n6. **HTTP Endpoint Discovery:**\n - HTTP vals have a `links.endpoint` field with the live deployment URL\n - Use this to test and verify your val is working correctly",[163],"45bc0944-fa5f-11f0-8ddd-42dde27851f2",".vtignore","45bc0a0c-fa5f-11f0-8ddd-42dde27851f2",4,["D",1769394754640],".git\n.vscode\n.cursor\n.DS_Store\nnode_modules\nvendor",[170],"1c1fde9e-fa64-11f0-b434-42dde27851f2","shared","1c1fdf34-fa64-11f0-b434-42dde27851f2",13,["D",1769396832395],[177],"1c023452-fa64-11f0-b434-42dde27851f2","frontend","1c023524-fa64-11f0-b434-42dde27851f2",11,["D",1769396832199],[183],"7fbad802-fa62-11f0-aa45-42dde27851f2","docs","7fbad906-fa62-11f0-aa45-42dde27851f2",8,["D",1769396140514],[189],"1c130b42-fa64-11f0-b434-42dde27851f2","backend","1c130be2-fa64-11f0-b434-42dde27851f2",12,["D",1769396832312],[195],"7fad8328-fa62-11f0-aa45-42dde27851f2",".claude","7fad83be-fa62-11f0-aa45-42dde27851f2",7,["D",1769396140425],[201],"pulls","branches","forks","envVars",{"_213":152,"_215":152},"connections",{"_213":152,"_214":152},"count","unfilledCount","emptyCount",{"_41":200,"_31":201,"_29":202,"_140":-5,"_39":40,"_38":203,"_142":57,"_36":285,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":286,"_26":287},{"_41":277,"_31":278,"_29":279,"_140":202,"_39":40,"_38":280,"_142":24,"_36":281,"_13":152,"_33":20,"_35":282,"_23":24,"_145":-5,"_231":283,"_26":284},{"_41":194,"_31":195,"_29":196,"_140":-5,"_39":40,"_38":197,"_142":57,"_36":274,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":275,"_26":276},{"_41":267,"_31":268,"_29":269,"_140":196,"_39":40,"_38":270,"_142":57,"_36":271,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":272,"_26":273},{"_41":263,"_31":32,"_29":30,"_140":196,"_39":40,"_38":14,"_142":57,"_36":264,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":265,"_26":266},{"_41":188,"_31":189,"_29":190,"_140":-5,"_39":40,"_38":191,"_142":57,"_36":260,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":261,"_26":262},{"_41":252,"_31":253,"_29":254,"_140":190,"_39":40,"_38":255,"_142":57,"_36":256,"_13":152,"_33":20,"_35":257,"_23":24,"_145":-5,"_231":258,"_26":259},{"_41":182,"_31":183,"_29":184,"_140":-5,"_39":40,"_38":185,"_142":57,"_36":249,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":250,"_26":251},{"_41":176,"_31":177,"_29":178,"_140":-5,"_39":40,"_38":179,"_142":57,"_36":246,"_13":152,"_33":34,"_35":-5,"_23":24,"_145":-5,"_231":247,"_26":248},{"_41":169,"_31":170,"_29":171,"_140":-5,"_39":40,"_38":172,"_142":57,"_36":243,"_13":152,"_33":20,"_35":174,"_23":24,"_145":-5,"_231":244,"_26":245},{"_41":162,"_31":163,"_29":164,"_140":-5,"_39":40,"_38":165,"_142":24,"_36":240,"_13":152,"_33":20,"_35":167,"_23":24,"_145":-5,"_231":241,"_26":242},{"_41":155,"_31":156,"_29":157,"_140":-5,"_39":40,"_38":158,"_142":57,"_36":237,"_13":152,"_33":20,"_35":160,"_23":24,"_145":-5,"_231":238,"_26":239},{"_41":147,"_31":148,"_29":149,"_140":-5,"_39":40,"_38":150,"_142":57,"_36":234,"_13":152,"_33":20,"_35":153,"_23":24,"_145":-5,"_231":235,"_26":236},{"_41":137,"_31":138,"_29":139,"_140":-5,"_39":40,"_38":141,"_142":57,"_36":230,"_13":61,"_33":20,"_35":144,"_23":24,"_145":-5,"_231":232,"_26":233},["D",1769394772448],"children",[],[138],["D",1769394754649],[],[148],["D",1769394754645],[],[156],["D",1769394754653],[],[163],["D",1769394754640],[],[170],["D",1769396832395],[],[177],["D",1769396832199],[],[183],"7fd0897c-fa62-11f0-b9fa-42dde27851f2","spec.md","7fd08a30-fa62-11f0-b9fa-42dde27851f2",9,["D",1769396140653],"# X Article Reader - Val Town Project Specification\n\n## Project Overview\n\nA Val Town application that formats X.com (formerly Twitter) article-style posts in a clean, aesthetically pleasing reading experience. The application fetches content from the FXTwitter API and displays it with minimal black and white design, optimized for readability.\n\n## Core Functionality\n\n### URL Routing Pattern\n- **Pattern**: `x.com/user/status/id` → `subdomain.val.run/user/status/id`\n- **Support**: Accept both `x.com` and `twitter.com` domains\n- **Normalization**: Internally normalize all URLs to x.com format before processing\n\n### User Interface\n- **Primary Interface**: Interactive web page with URL input form\n- **Homepage**: Landing page with description, input form, and instructional examples showing the URL pattern\n- **Example Content**: Balance between showing example threads and clear instructions on how to use the service\n\n### Content Scope\n- **Target Content**: Article threads only (long-form thread articles)\n- **Article Format**: API provides article content in a single structure (not individual threaded tweets)\n- **Display**: Single continuous article view\n\n## Design & Aesthetics\n\n### Visual Design\n- **Style**: Minimal black and white design\n- **Purpose**: Distraction-free, focus entirely on readability and content\n- **Color Palette**: Pure black text on white background, no dynamic theming from API color data\n\n### Typography\n- **Font Family**: Modern sans-serif (system fonts for fast loading)\n- **Font Stack**: `system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`\n- **Content Width**: Maximum ~650px for optimal readability (65-75 characters per line)\n- **Responsive**: Centered content with padding on larger screens\n\n### Layout Structure\n1. **Hero Image**: Cover media displayed as large hero image at top\n2. **Article Title**: Large H1 heading below hero image\n3. **Author Information**: Display name + avatar image\n4. **Metadata**: Publication date (relative format: \"2 hours ago\", \"yesterday\" for recent; full date for older)\n5. **Article Content**: Full formatted content with proper spacing\n6. **Footer**: Link to view original on X.com\n\n## Content Rendering\n\n### Article Content Formatting\n- **Rendering Style**: Full formatting support\n- **Supported Elements**:\n - Headers (H2/H3 for header-two, etc.)\n - Unordered and ordered lists (`

Unable to load article

[Contextual error message]

\n View on X.com\n

[Article Title] - [Author Name]

\n $\"Cover$ \n\n

[Article Title]

\n\n

\n $\"[author.name]\"$ \n [author.name]\n

\n\n [Relative date]\n

\n\n

\n [Rendered blocks with full formatting]\n

\n\n \n

 with highlighting\n};\n```\n\n### Inline Style Processing\n```typescript\nfunction applyInlineStyles(text: string, ranges: InlineStyleRange[]): string {\n  // Sort ranges by offset\n  // Apply BOLD → , ITALIC → , etc.\n  // Handle overlapping ranges correctly\n  // Return HTML string with inline formatting\n}\n```\n\n### Entity Range Processing\n```typescript\nfunction applyEntityRanges(text: string, ranges: EntityRange[], entityMap: EntityMap): string {\n  // For each entity range:\n  // - Extract entity from entityMap by key\n  // - Apply appropriate transformation:\n  //   - LINK → text\n  //   - CODE → text\n  //   - Handle other entity types as needed\n  // Return HTML string with entities processed\n}\n```\n\n## Performance Considerations\n\n### Optimization Strategy\n- **Load Everything**: Render complete article at once (no pagination or lazy loading)\n- **Minimal Dependencies**: Only essential libraries loaded\n- **SQLite Cache**: Reduces API calls and improves response time for repeated views\n- **Static HTML**: No client-side JavaScript on article pages (except Highlight.js initialization)\n- **Content Width**: Fixed max-width prevents excessive line length and maintains readability\n\n### Bundle Size Goals\n- **Core HTML/CSS**: < 10KB\n- **Highlight.js**: < 50KB (core + common languages only)\n- **Total Initial Load**: < 100KB excluding images\n- **Time to First Byte**: < 200ms (cached), < 1s (uncached)\n\n## Privacy & Analytics\n\n### Privacy-First Approach\n- **No Tracking**: No analytics or user behavior logging\n- **No Cookies**: No cookies set or required\n- **No Third-Party Scripts**: Only self-hosted or CDN resources (Highlight.js)\n- **No User Data Storage**: Only article content cached, no user identifiers\n\n### Logging\n- **Application Logs**: Server-side errors logged for debugging\n- **No Access Logs**: Do not log article views or user behavior\n- **Error Tracking**: Only log failed API requests for debugging purposes\n\n## Social Sharing & Metadata\n\n### OpenGraph Tags\n```html\n\n\n\n\n\n```\n\n### Page Title\n```html\n[Article Title] by [Author Name]\n```\n\n## Date Formatting\n\n### Relative Date Logic\n```typescript\nfunction formatDate(timestamp: string): string {\n  const date = new Date(timestamp);\n  const now = new Date();\n  const diffInHours = (now - date) / (1000 * 60 * 60);\n\n  if (diffInHours < 1) return \"Just now\";\n  if (diffInHours < 24) return `${Math.floor(diffInHours)} hours ago`;\n  if (diffInHours < 48) return \"Yesterday\";\n  if (diffInHours < 168) return `${Math.floor(diffInHours / 24)} days ago`;\n\n  // For older articles, show full date\n  return date.toLocaleDateString('en-US', {\n    year: 'numeric',\n    month: 'long',\n    day: 'numeric'\n  });\n}\n```\n\n## Implementation Checklist\n\n### Backend\n- [ ] Set up Hono app with route handlers\n- [ ] Implement SQLite schema and caching logic\n- [ ] Create FXTwitter API client with error handling\n- [ ] Build URL parser for both x.com and twitter.com\n- [ ] Implement cache lookup and storage\n- [ ] Create article renderer (blocks → HTML)\n- [ ] Build error page template\n\n### Frontend\n- [ ] Design minimal CSS stylesheet\n- [ ] Create homepage HTML template\n- [ ] Build article page HTML template\n- [ ] Integrate Highlight.js for syntax highlighting\n- [ ] Implement inline style ranges rendering\n- [ ] Implement entity ranges rendering\n- [ ] Add OpenGraph meta tags\n- [ ] Style error pages\n\n### Testing\n- [ ] Test with various article types\n- [ ] Verify cache expiration logic\n- [ ] Test error scenarios (404, API down, etc.)\n- [ ] Validate URL parsing for both domains\n- [ ] Check rendering of all block types\n- [ ] Verify syntax highlighting works\n- [ ] Test social sharing metadata\n- [ ] Mobile responsiveness testing\n\n### Deployment\n- [ ] Deploy to Val Town\n- [ ] Verify endpoint URL\n- [ ] Test live with real X.com articles\n- [ ] Monitor for errors\n- [ ] Document usage\n\n## Future Considerations (Out of Scope for v1)\n\n- Dark mode toggle\n- Reader preferences (font size, width)\n- Article bookmarking/favorites\n- RSS feed generation\n- Print-optimized styling\n- Reading time estimates\n- Multi-language support\n- Search functionality\n- Article collections/categorization\n\n## Success Criteria\n\n1. **Functionality**: Successfully formats X.com article threads with proper rendering\n2. **Performance**: Pages load in < 2 seconds including images\n3. **Readability**: Clean, distraction-free reading experience\n4. **Reliability**: Graceful error handling for all edge cases\n5. **Simplicity**: Minimal dependencies, straightforward codebase\n6. **Privacy**: No tracking or unnecessary data collection\n",[],[189,253],["D",1769396140514],[222],[189],"1c3ecb9c-fa64-11f0-b434-42dde27851f2",["D",1769396832596],[],[195,32],"1c3091f8-fa64-11f0-859c-42dde27851f2","database","1c3092a2-fa64-11f0-859c-42dde27851f2",14,["D",1769396832501],[],[195,268],["D",1769396832312],[219,220],[195],"7fd5874c-fa62-11f0-9216-42dde27851f2","settings.local.json","7fd58800-fa62-11f0-9216-42dde27851f2",10,["D",1769396140655],"{\n  \"permissions\": {\n    \"allow\": [\n      \"WebFetch(domain:api.fxtwitter.com)\"\n    ]\n  }\n}\n",[],[201,278],["D",1769396140425],[217],[201],["D",1769394726777],["D",1789533091345],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":53,"_102":103,"_104":24},{"_13":87,"_31":88,"_41":40,"_89":42,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":43,"_96":97},"ctx",{"_80":-5,"_124":326,"_327":328,"_329":330,"_331":24,"_332":24,"_333":24,"_334":57,"_335":-5,"_336":-7,"_337":-7,"_338":152,"_339":24,"_340":24,"_341":-5,"_342":24,"_343":24,"_344":24,"_345":-5},"ENV",{"_297":298,"_299":300,"_301":88,"_302":303,"_304":305,"_306":307,"_308":309,"_310":311,"_312":313,"_314":315,"_316":317,"_318":319,"_320":321,"_322":323,"_324":325},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v15