This plan addresses refactoring, cleanup, organization, and key design principles (KISS, YAGNI, SoC, SRP, DRY) with beginner‑friendly names. Each step includes updating App.tsx for testing and pushing to Val Town.

• 1.1 Create src directory if it doesn't exist
• 1.2 Create src/builders directory
• 1.3 Remove empty folders (src/client, src/server) - Note: Created remove_empty_dirs.sh script, needs to be executed manually
• 1.4 Create src/types.ts with basic shared type definitions
  • Doc interface
  • Config interface
  • Heading interface
• 1.5 Update App.tsx to import types (minimal change)
• 1.6 Run vt push to test basic structure - Note: Needs to be executed manually

• 2.1 Create src/utils.ts with helper functions
  • loadDoc function
  • DocTreeNode interface
  • NestedGroupedDocs interface
  • Simple groupByFolder function (renamed from groupDocsByFolder)
• 2.2 Update App.tsx to use the new utils.ts
• 2.3 Run vt push to test utility functions - Note: Fixed duplicate import and variable declaration issues. Also fixed document path handling in loadDoc function.

• 3.1 Create src/plugins.ts with remark/rehype plugins
  • remarkCallout plugin with fixed regex pattern
  • rehypeCallout plugin
• 3.2 Update App.tsx to use the new plugins.ts
• 3.3 Run vt push to test plugins

• 4.1 Create src/parser.ts with unified parser setup
  • Import and configure remark plugins
  • Import and configure rehype plugins
  • Remove remarkLint (move to dev chain)
• 4.2 Update App.tsx to use the new parser.ts
• 4.3 Run vt push to test parser

• 5.1 Create src/config.ts
  • Define config object with all settings
  • Create helper to resolve all stylesheet paths once
  • Define docs array with document list
• 5.2 Remove any existing config files or duplicate configuration code
• 5.3 Update App.tsx to use the new config.ts
• 5.4 Run vt push to test configuration

• 6.1 Create src/builders/navigation.ts
  • buildNav function (renamed from docLinksHtml)
  • buildSidebar function (renamed from sidebarHtml)
• 6.2 Remove navigation-related functions from App.tsx
• 6.3 Update App.tsx to use the new navigation.ts
• 6.4 Run vt push to test navigation

• 7.1 Create src/builders/head.ts
  • buildHead function
• 7.2 Remove head-related functions from App.tsx
• 7.3 Update App.tsx to use the new head.ts
• 7.4 Run vt push to test head builder

• 8.1 Create src/builders/scripts.ts
  • buildScripts function
• 8.2 Remove scripts-related functions from App.tsx
• 8.3 Update App.tsx to use the new scripts.ts
• 8.4 Run vt push to test scripts builder

• 9.1 Enhance utils.ts with buildToc function
• 9.2 Create src/handlers.ts
  • renderDoc function (renamed from processDocument)
  • appHandler function (renamed from handleRequest)
• 9.3 Remove handler-related functions from App.tsx
• 9.4 Update App.tsx to use the new handlers.ts
• 9.5 Run vt push to test handlers

• 10.1 Simplify App.tsx to be a thin wrapper
  • Import appHandler from src/handlers.ts
  • Export appHandler as default
  • Remove ALL remaining implementation code from App.tsx
• 10.2 Run vt push to test final implementation
• 10.3 Verify all functionality works as expected

• Ensure old utility functions are removed from App.tsx as they're moved to utils.ts
• Ensure old plugin definitions are removed from App.tsx as they're moved to plugins.ts
• Ensure old parser setup is removed from App.tsx as it's moved to parser.ts
• Ensure old configuration is removed as it's moved to config.ts
• Ensure old navigation functions are removed as they're moved to navigation.ts
• Ensure old head-building functions are removed as they're moved to head.ts
• Ensure old script-building functions are removed as they're moved to scripts.ts
• Ensure old handler functions are removed as they're moved to handlers.ts
• Verify no duplicate code exists between App.tsx and the new module files

• After each vt push, verify the app still works correctly
• If issues are found, fix them before moving to the next step
• Keep a backup of the working version before each major change
• Check browser console for any errors during testing
• When removing code from App.tsx, ensure it's properly moved to the new files first