[CRITICAL] Fix routing and layout bugs identified in recent commits [Si...

[devwif]

[CRITICAL] Fix Routing and Layout Bugs Identified in Recent Commits

---

🚨 Problem Statement

Our WebTUI library is currently suffering from critical routing and layout bugs introduced by recent commits (notably PR #7). These bugs are causing broken navigation and visual inconsistencies in example components, significantly degrading developer experience, usability, and confidence in the library. If left unresolved, these issues risk stalling adoption and community contributions.

Our mission: Restore flawless routing and pixel-perfect layouts across all example components immediately, ensuring a stable foundation for future growth and external contributions.

---

🔍 Technical Context

• Repository: aldrin-labs/webtui
• Primary Language: Astro + TypeScript
• Tech Stack: @biomejs/biome, turbo, typescript
• Recent Problematic Commit: Merge pull request Fix layout issues in example components and add new components from rinlab.com #7 — fixed layout issues but introduced new routing bugs and partial layout regressions.
• Scope: Example components used for demos and documentation site routing.
• Current Symptoms:
  • Navigation between example components breaks or leads to 404s.
  • Layout issues: overlapping elements, broken flex/grid containers, inconsistent padding/margins.
• Risk Level: High — affects core UX, developer confidence, and security posture (broken routing may expose unhandled errors).
• Project Phase: Early development with foundational components and theming support.

---

🛠️ Detailed Implementation Steps

1. Reproduce and Document Bugs

   • Clone the latest main branch.
   • Run npm run dev or pnpm dev to start the dev server.
   • Navigate through example components, especially those changed in PR Fix layout issues in example components and add new components from rinlab.com #7.
   • Capture screenshots, console errors, and routing failures.
   • Document exact defect scenarios in a temporary bug report doc or issue comments.

2. Investigate Root Causes

   • Audit routing configuration files (Astro routes, biome config, etc.).
   • Inspect layout CSS and component structure (flex/grid rules, Astro components).
   • Compare with last known good commit before PR Fix layout issues in example components and add new components from rinlab.com #7.
   • Identify any breaking API changes or incorrect imports.

3. Research Best Practices

   • Review Astro routing docs: https://docs.astro.build/en/core-concepts/routing/
   • Review biomejs usage patterns for routing and CSS integration.
   • Check terminal UI layout best practices for consistent spacing and responsiveness.

4. Implement Fixes

   • Correct routing paths and config to ensure all example components are reachable.
   • Refactor layout components/CSS to fix visual bugs (e.g., fix flexbox gaps, container widths).
   • Add or adjust Astro frontmatter if needed to fix page metadata and routing.
   • Ensure routing uses proper client-side hydration if applicable.

5. Testing & Validation

   • Write or update automated tests for routing (integration/e2e tests).
   • Manually verify navigation flow and layout correctness across all example components.
   • Use browser dev tools to check for layout issues on multiple screen sizes.
   • Run accessibility audits (Lighthouse, axe-core) to ensure no regressions.

6. Documentation

   • Update README or docs/webtui-routing.md with correct routing setup.
   • Document layout component usage and CSS patterns.
   • Add a troubleshooting section for common routing/layout issues in examples.

7. Code Review & Merge

   • Submit PR with detailed description and screenshots before/after.
   • Request reviews from core maintainers.
   • Merge after approvals and successful CI runs.

---

📋 Technical Specifications

• Routing must follow Astro conventions: route files placed in /src/pages or /src/pages/examples.
• Routing config must support client-side navigation without page reload glitches.
• Layout components should:
  • Use CSS Grid or Flexbox with consistent spacing tokens from the theming system.
  • Avoid fixed widths/heights that break responsiveness.
  • Follow WebTUI’s modular CSS architecture (BEM or utility-first as applicable).
• Tests must cover:
  • Navigation to each example component.
  • Layout validations (snapshots or visual regression tests).
• Documentation style should follow existing WebTUI docs conventions (Markdown + code snippets).

---

✅ Acceptance Criteria

• Root causes of routing failures and layout bugs are identified and documented.
• All example components load correctly via navigation without 404s or errors.
• Layouts render correctly with consistent spacing, alignment, and no visual regressions.
• Automated tests for routing and layout pass without failures.
• Accessibility audit shows no new issues introduced.
• Documentation updated with routing and layout fixes, including troubleshooting notes.
• No regressions introduced in unrelated parts of the codebase.
• PR passes CI and receives approvals from maintainers.

---

🧪 Testing Requirements

• Manual exploratory testing of all example component routes.
• Cross-browser visual checks (Chrome, Firefox, Safari).
• Responsive testing on desktop and mobile viewport widths.
• Automated integration/e2e tests simulating navigation flows.
• CSS regression tests (if feasible).
• Lighthouse accessibility and SEO audits.

---

📚 Documentation Needs

• Update or create a Routing Guide in docs describing:
  • How routing is structured in WebTUI examples.
  • Common pitfalls & fixes.
• Add a Layout Troubleshooting section documenting:
  • Known layout bugs and how they were fixed.
  • Best practices for layout components in WebTUI.
• Update README with a note about the critical fix and encourage contributors to test routing/layout locally.

---

⚠️ Potential Challenges & Risks

• Astro routing nuances may cause unexpected client/server hydration mismatches.
• Layout fixes might conflict with existing theming rules or CSS variables.
• Risk of introducing regressions in unrelated example components if tests are incomplete.
• Limited test coverage currently increases manual testing burden.
• Time pressure due to critical priority may push rushed fixes; thorough review required.

---

📖 Resources & References

• Astro Routing Documentation: https://docs.astro.build/en/core-concepts/routing/
• BiomeJS Official Site and Docs: https://biomejs.dev
• WebTUI Documentation Site: https://webtui.ironclad.sh
• PR Fix layout issues in example components and add new components from rinlab.com #7 (for context): Fix layout issues in example components and add new components from rinlab.com #7
• CSS Flexbox Guide: https://css-tricks.com/snippets/css/a-guide-to-flexbox/
• Accessibility Testing Tools: https://www.deque.com/axe/

---

Let's fix this beast and bring back the smooth developer joy WebTUI deserves! 🚀

---

Checklist before closing this issue:

• Bug reproduction steps documented
• Root cause analysis complete
• Fix implemented and committed
• Tests added/updated and passing
• Documentation updated accordingly
• Code reviewed and merged

---

Issue authored by your friendly neighborhood senior software engineer, ready to conquer chaos one bug at a time.