docs: Add comprehensive project summary

PROJECT_SUMMARY.md

@@ -0,0 +1,231 @@
+# IF.docs.md2html - Project Summary
+
+## What We Built
+
+A **magazine-style Markdown viewer** that transforms plain `.md` files into beautiful, animated documents using the **ICW NextSpread design system** from icantwait.ca property showcase.
+
+## Key Features
+
+### 🎨 Design System (Ported from ICW)
+- **Typography**: Inter headings, system fonts for body, JetBrains Mono for code
+- **Colors**: Neutral palette (50-900), Primary green (#10B981)
+- **Spacing**: 8-point grid system, generous white space
+- **Animations**: Webflow-style ease curves `[0.25, 0.46, 0.45, 0.94]`
+
+### ✨ Animations (ICW Property Page Patterns)
+- **Adaptive Duration**: Animation speed adjusts to scroll velocity
+  - Fast scroll = shorter animations (0.5x speed)
+  - Slow scroll = longer animations (1.5x speed)
+- **Staggered Reveals**: Gallery-style cascade with 50ms delays
+- **Scroll Triggers**: IntersectionObserver with -10% margin
+- **Reduced Motion**: Respects accessibility preferences
+
+### 📱 Layout
+- **Magazine Grid**: 2-column main content + 1-column sidebar (desktop)
+- **Full-Bleed Hero**: 40vh mobile, 50vh desktop with gradient overlay
+- **Sticky Sidebar**: Navigation panel follows scroll
+- **Responsive**: Mobile-first (320px) → Desktop (1440px+)
+
+### 🚀 Functionality
+- **Drag-and-Drop Upload**: `.md` and `.markdown` files
+- **URL Parsing**: `?parse=https://url/file.md` query parameter
+- **Syntax Highlighting**: VS Code Dark+ theme via highlight.js
+- **Static Export**: Pre-rendered HTML for fast loading
+
+## Components
+
+### HeroSection (`src/components/HeroSection.tsx`)
+- Full-bleed hero with gradient overlay
+- Animated badge, title, CTA buttons
+- ICW-style drop shadows and backdrop blur
+
+### MagazineContent (`src/components/MagazineContent.tsx`)
+- 2-column grid layout
+- Staggered element reveals via IntersectionObserver
+- Sticky sidebar with navigation
+
+### MarkdownViewer (`src/components/MarkdownViewer.tsx`)
+- Main wrapper component
+- Orchestrates hero + content sections
+- Adaptive animation timing
+
+### FileUploader (`src/components/FileUploader.tsx`)
+- Drag-and-drop zone with hover states
+- File input fallback
+- Loading spinner and error states
+
+## Animation Hooks
+
+### useAdaptiveDuration (`src/lib/useAdaptiveDuration.ts`)
+```typescript
+// Adjusts animation speed based on scroll velocity
+const duration = useAdaptiveDuration(0.6); // Base 0.6s
+// Returns: 0.3s (fast scroll) → 0.9s (slow scroll)
+```
+
+### useScrollSpeed (`src/lib/useScrollSpeed.ts`)
+```typescript
+// Measures scroll velocity (0-100 scale)
+const scrollSpeed = useScrollSpeed();
+// 0 = stationary, 100 = max speed (5000px/s)
+```
+
+### useClientReady (`src/lib/useClientReady.ts`)
+```typescript
+// Prevents hydration mismatches
+const isReady = useClientReady();
+if (!isReady) return <Skeleton />;
+```
+
+## Styling
+
+### Markdown Prose (`src/styles/markdown.css`)
+- **Headings**: -0.02em letter spacing, tracking-tight
+- **Drop Cap**: First paragraph first letter (6xl, float left)
+- **Lead Paragraph**: First paragraph 2xl size
+- **Links**: Underline on hover with smooth transition
+- **Blockquotes**: Magazine pull-quote style with left border
+- **Code Blocks**: Rounded corners, VS Code theme
+- **Images**: Full-width with rounded corners and shadows
+
+### Syntax Highlighting (`src/styles/highlight.css`)
+- VS Code Dark+ theme colors
+- Background: `#1e1e1e`
+- Keywords: `#569cd6` (blue)
+- Strings: `#ce9178` (orange)
+- Comments: `#6a9955` (green)
+
+## Deployment Configuration
+
+### Next.js Config (`next.config.mjs`)
+```javascript
+{
+  output: 'export',                           // Static export
+  basePath: '/infrafabric/IF.docs.md2html',  // StackCP path
+  images: { unoptimized: true }              // No image optimization
+}
+```
+
+### Apache Config (`.htaccess`)
+- SPA routing (all requests → index.html)
+- CORS headers for external markdown fetching
+- Gzip compression for text files
+- Browser caching (1 hour HTML, 1 month CSS/JS)
+
+## Usage Examples
+
+### Local Development
+```bash
+npm install
+npm run dev
+# Open http://localhost:3000
+```
+
+### File Upload
+1. Drag `.md` file onto dropzone
+2. Or click "Choose File" button
+3. Document renders with magazine layout + animations
+
+### URL Parsing
+```
+http://localhost:3000?parse=https://raw.githubusercontent.com/user/repo/main/README.md
+```
+
+### Production (StackCP)
+```
+https://digital-lab.ca/infrafabric/IF.docs.md2html
+https://digital-lab.ca/infrafabric/IF.docs.md2html?parse=https://example.com/docs.md
+```
+
+## File Structure
+
+```
+IF.docs.md2html/
+├── src/
+│   ├── app/
+│   │   ├── layout.tsx              # Root layout
+│   │   └── page.tsx                # Home page (Suspense wrapper)
+│   ├── components/
+│   │   ├── FileUploader.tsx        # Drag-and-drop UI
+│   │   ├── HeroSection.tsx         # ICW-style hero
+│   │   ├── MagazineContent.tsx     # Magazine layout
+│   │   ├── MarkdownViewer.tsx      # Main viewer
+│   │   └── ViewerContent.tsx       # URL param handler
+│   ├── lib/
+│   │   ├── markdown-parser.ts      # markdown-it config
+│   │   ├── useAdaptiveDuration.ts  # Animation hook
+│   │   ├── useScrollSpeed.ts       # Scroll tracker
+│   │   └── useClientReady.ts       # Hydration guard
+│   └── styles/
+│       ├── globals.css             # Base + Tailwind
+│       ├── markdown.css            # Prose styling
+│       └── highlight.css           # Code theme
+├── out/                            # Build output
+├── .htaccess                       # Apache config
+├── DEPLOY.md                       # Deployment guide
+├── README.md                       # User documentation
+└── PROJECT_SUMMARY.md              # This file
+```
+
+## Technical Highlights
+
+### Performance
+- **Static Export**: Pre-rendered HTML, no server required
+- **Code Splitting**: Automatic via Next.js
+- **Lazy Loading**: Images below fold
+- **Gzip Compression**: ~70% size reduction
+- **First Load**: 477 kB (main page)
+
+### Accessibility
+- **Reduced Motion**: Respects `prefers-reduced-motion`
+- **Keyboard Navigation**: Tab order, focus indicators
+- **Semantic HTML**: Proper heading hierarchy
+- **Touch Targets**: 44px+ minimum size
+
+### Browser Support
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS 14+, Android Chrome 90+)
+
+## Design Credits
+
+**Ported from ICW NextSpread** (icantwait.ca):
+- Property page animations (HeroEditorial, Gallery, About components)
+- Adaptive duration timing system
+- Scroll-speed-based animation adjustments
+- Webflow-style easing curves
+- Typography scale and color palette
+- Touch target sizes and spacing
+
+**Inspired by**:
+- Airbnb editorial pages (magazine layouts)
+- Medium long-form articles (typography)
+- Notion docs (clean, readable prose)
+
+## Repository
+
+- **GitHub**: https://github.com/dannystocker/IF.docs.md2html
+- **Branch**: `main`
+- **Commit**: f950357
+
+## Next Steps
+
+1. **Deploy to StackCP**: Follow `DEPLOY.md` instructions
+2. **Test URL parsing**: Try with InfraFabric docs
+3. **Add features**:
+   - Table of contents sidebar
+   - Dark mode toggle
+   - Export to PDF
+   - Social sharing
+   - Print stylesheet
+
+## License
+
+MIT
+
+---
+
+**Created**: 2025-11-14
+**Author**: Claude Code
+**Design System**: ICW NextSpread (icantwait.ca)