feat(seo): add complete SEO optimization and analytics

- Add meta tags (description, Open Graph, Twitter cards) to all pages
- Add structured data (JSON-LD) with SoftwareApplication schema
- Create sitemap.xml and robots.txt
- Add Plausible Analytics tracking
- Create web-safe SVG favicon with monospace 'F'
- Fix navigation paths to use relative URLs for sub-path deployment support
- Fix active link detection in NavBar component
- Add preconnect/dns-prefetch for esm.sh CDN

Package & Documentation:
- Add sideEffects: false and publishConfig to package.json
- Enhance README with TOC, badges, and quick links
- Add Conventional Commits and branch naming to CONTRIBUTING.md
- Create comprehensive PR template
- Update DEVELOPMENT.md to focus on Cloudflare Pages deployment

All tests pass (74/74) and bundle size remains at 1.30KB gzipped.

Author: watthem

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,63 @@
+## Description
+
+<!-- Provide a brief summary of your changes -->
+
+## Related Issue
+
+<!-- Link to related issue(s) if applicable -->
+Fixes #
+
+## Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code refactoring
+- [ ] Performance improvement
+- [ ] Test addition or update
+
+## Checklist
+
+### Code Quality
+- [ ] My code follows the project's code style guidelines
+- [ ] I have added JSDoc comments for new public APIs
+- [ ] I have kept functions small and focused
+- [ ] Error handling is graceful and non-fatal
+
+### Testing
+- [ ] I have run `npm test` and all tests pass
+- [ ] I have tested manually with the examples (Todo app, etc.)
+- [ ] I have added/updated tests for my changes
+- [ ] XSS protection test passes (if applicable)
+
+### Bundle Size
+- [ ] I have run `npm run size-check` and the bundle stays under 5KB
+- [ ] If adding features, I considered removing or optimizing existing code
+
+### Documentation
+- [ ] I have updated the README (if applicable)
+- [ ] I have updated `wiki/API.md` (if applicable)
+- [ ] I have updated `docs/BLUEPRINT.md` for architectural changes
+- [ ] I have verified alignment with `wiki/STANDARDS.md`
+
+### Security
+- [ ] My changes do not introduce `eval()` or `new Function()`
+- [ ] All user input is validated
+- [ ] User content is properly escaped (via uhtml)
+- [ ] No server closures or function serialization
+
+### Deployment
+- [ ] My changes work on both root domain and sub-path deployments
+- [ ] I have tested locally with `npx serve`
+- [ ] Relative paths are used (no hardcoded absolute paths starting with `/`)
+
+## Screenshots (if applicable)
+
+<!-- Add screenshots to help explain your changes -->
+
+## Additional Notes
+
+<!-- Any additional information that reviewers should know -->

CONTRIBUTING.md

@@ -57,6 +57,14 @@ We welcome contributions! Please read the [Blueprint](./docs/BLUEPRINT.md) and [
    ```bash
    git checkout -b feat/your-feature-name
    ```
+   
+   **Branch Naming Convention:**
+   - `feat/` - New features
+   - `fix/` - Bug fixes
+   - `docs/` - Documentation changes
+   - `chore/` - Maintenance tasks
+   - `refactor/` - Code refactoring
+   - `test/` - Test additions or modifications
 
 3. **Make your changes:**
    - Follow existing code style
@@ -73,7 +81,24 @@ We welcome contributions! Please read the [Blueprint](./docs/BLUEPRINT.md) and [
    npm run format
    ```
 
-6. **Submit a PR:**
+6. **Commit with Conventional Commits:**
+   ```bash
+   # Format: <type>(<scope>): <subject>
+   git commit -m "feat(reactivity): add cleanup support to run"
+   git commit -m "fix(hydration): handle invalid JSON gracefully"
+   git commit -m "docs(readme): add table of contents"
+   ```
+   
+   **Commit Types:**
+   - `feat:` - New feature
+   - `fix:` - Bug fix
+   - `docs:` - Documentation only changes
+   - `style:` - Code style changes (formatting, semicolons, etc)
+   - `refactor:` - Code refactoring
+   - `test:` - Adding or updating tests
+   - `chore:` - Maintenance tasks (build, deps, etc)
+
+7. **Submit a PR:**
    - Include description of changes
    - Reference any related issues
    - Ensure CI passes

DEVELOPMENT.md

@@ -52,22 +52,28 @@ npm run dev
 
 ## Deployment
 
-Both `website/` and `KB/` are pure static sites and can be deployed to any static hosting service.
+Both `website/` and `KB/` are pure static sites and can be deployed to Cloudflare Pages, Netlify, Vercel, or any static hosting service.
 
-### GitHub Pages
+### Cloudflare Pages (Recommended)
 
-#### Deploy Website
+The project is configured to deploy to Cloudflare Pages with the custom domain frontjs.dev.
+
+#### Deploy to Production
 
-1. Push your code to GitHub
-2. Go to repository Settings → Pages
-3. Set source to `website/` directory
-4. Your site will be available at `https://watthem.github.io/front-js/`
+```bash
+# Deploy to production (master branch)
+npm run deploy:cf:prod
+
+# Or deploy current state (including uncommitted changes)
+npm run deploy:cf
+```
 
-#### Deploy KB (Separate Site)
+The `website/` directory is deployed to https://frontjs.dev.
 
-You can deploy KB as a separate GitHub Pages site:
-1. Create a separate branch or repository for KB
-2. Or use GitHub Actions to deploy both
+**Configuration:**
+- Custom domain configured via `website/CNAME`
+- Deployment uses wrangler CLI
+- See `package.json` for deployment scripts
 
 ### Netlify
 

README.md

@@ -2,6 +2,32 @@
 
 **The secure-by-default, islands-first micro-framework.**
 
+[![NPM Version](https://img.shields.io/npm/v/@watthem/front-js.svg)](https://www.npmjs.com/package/@watthem/front-js)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![CI](https://github.com/watthem/front-js/actions/workflows/ci.yml/badge.svg)](https://github.com/watthem/front-js/actions/workflows/ci.yml)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@watthem/front-js)](https://bundlephobia.com/package/@watthem/front-js)
+
+**🌐 [Website](https://frontjs.dev)** | **📚 [Documentation](https://frontjs.dev/KB/)** | **💻 [Examples](https://frontjs.dev/examples/)**
+
+## Table of Contents
+
+- [Install](#install)
+- [Hello World](#hello-world)
+- [Why front.js?](#why-frontjs)
+- [Core Concepts](#core-concepts)
+  - [Values](#values)
+  - [Components](#components)
+  - [Hydration](#hydration)
+  - [Lifecycle Cleanup](#lifecycle-cleanup)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+- [Limitations](#limitations)
+- [Security Model](#security-model)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Install
 
 ```bash

notes/SEO-IMPLEMENTATION-SUMMARY.md

@@ -0,0 +1,173 @@
+# SEO Implementation Summary
+
+## ✅ Completed Changes
+
+### Phase 2: Navigation Fixes (CRITICAL - Fixed first)
+- ✅ **Fixed absolute path issues** in all HTML files
+  - Updated `index.html`, `examples/index.html`, `KB/index.html` to use relative paths
+  - Changed `/` to `./`, `/examples/` to `./examples/` or `../examples/`, etc.
+- ✅ **Fixed active link detection** in NavBar.js
+  - Replaced `currentPath.includes(link.url)` with proper URL pathname comparison
+  - Added `isLinkActive()` helper function that handles external links and normalizes paths
+
+### Phase 1: Website SEO Foundation
+- ✅ **Meta tags added** to all main pages (index.html, examples/index.html, KB/index.html)
+  - Meta descriptions (~150 chars)
+  - Canonical links
+  - Open Graph tags (title, description, url, image, type)
+  - Twitter card tags
+  - Favicon references
+  - Preconnect/DNS-prefetch for esm.sh CDN
+- ✅ **Structured data (JSON-LD)** added to index.html
+  - SoftwareApplication schema with full metadata
+- ✅ **Sitemap.xml** created with all pages
+  - Home, examples, KB, individual example pages
+- ✅ **Robots.txt** created with sitemap reference
+- ✅ **Favicon.svg** created with front.js branding
+
+### Phase 4: NPM Package Metadata
+- ✅ **package.json updated** with:
+  - `"sideEffects": false` for tree-shaking
+  - `"publishConfig": { "access": "public" }` for npm publishing
+
+### Phase 3: GitHub Repository Enhancements
+- ✅ **README.md enhanced** with:
+  - Table of contents with anchor links
+  - Additional badges (NPM version, CI, bundle size)
+  - Links to website, documentation, and examples at top
+- ✅ **CONTRIBUTING.md updated** with:
+  - Conventional Commits guidance
+  - Branch naming conventions (feat/, fix/, docs/, etc.)
+  - Commit message format examples
+- ✅ **PR template created** (.github/PULL_REQUEST_TEMPLATE.md)
+  - Comprehensive checklist covering code quality, testing, bundle size, docs, security
+- ✅ **GitHub topics added** via gh CLI:
+  - micro-framework, signals, esm, security-first, xss-protection
+- ✅ **DEVELOPMENT.md updated**
+  - Removed GitHub Pages deployment references
+  - Kept only Cloudflare Pages deployment instructions
+
+## 🔨 Manual Actions Required
+
+### 1. Generate OG Image (Priority: Medium)
+**File:** `website/og-image-generator.html` (template created)
+
+**Action:**
+1. Open `website/og-image-generator.html` in a browser
+2. Take a screenshot at exactly 1200x630 resolution
+3. Save as `website/og-image.png`
+
+**Alternative:** Use Puppeteer or similar tool to automate:
+```bash
+# Example with Puppeteer
+npx puppeteer screenshot website/og-image-generator.html website/og-image.png --viewport 1200x630
+```
+
+**Note:** Meta tags already reference `/og-image.png`, so once generated it will work automatically.
+
+### 2. Generate favicon.ico (Priority: Low)
+**File:** `website/favicon.svg` (SVG created)
+
+**Action:**
+Convert SVG to ICO format (optional, modern browsers use SVG):
+```bash
+# Using ImageMagick (if installed)
+convert website/favicon.svg -resize 32x32 website/favicon.ico
+
+# Or use an online converter
+# Upload favicon.svg to https://convertio.co/svg-ico/
+```
+
+### 3. Test Locally (Priority: High)
+**Action:**
+```bash
+cd website
+npx serve . -p 8000
+```
+
+**Verify:**
+- [ ] Navigation works on all pages (home, examples, KB)
+- [ ] Active link highlighting displays correctly
+- [ ] Favicon appears in browser tab
+- [ ] All pages load without console errors
+
+### 4. Deploy to Cloudflare Pages (Priority: High)
+**Action:**
+```bash
+# From project root
+npm run deploy:cf:prod
+```
+
+**Post-deployment verification:**
+- [ ] Visit https://frontjs.dev and verify it loads
+- [ ] Test navigation between pages
+- [ ] Check https://frontjs.dev/robots.txt loads
+- [ ] Check https://frontjs.dev/sitemap.xml loads
+- [ ] Test Open Graph tags using https://www.opengraph.xyz/ or similar
+
+### 5. Submit to Search Engines (Priority: Medium)
+**Google Search Console:**
+1. Verify ownership of frontjs.dev
+2. Submit sitemap: https://frontjs.dev/sitemap.xml
+3. Request indexing for key pages
+
+**Bing Webmaster Tools:**
+1. Verify ownership
+2. Submit sitemap
+
+### 6. Future: Add Meta Tags to Individual Example Pages (Priority: Low)
+The following example HTML files still need meta tags added:
+- `website/examples/todo.html`
+- `website/examples/calculator.html`
+- `website/examples/pixel-art.html`
+- `website/examples/gm-board.html`
+- `website/examples/walking-timer.html`
+- `website/examples/navbar.html`
+- `website/examples/github-user.html`
+
+Follow the same pattern as examples/index.html with page-specific descriptions.
+
+## 📊 Verification Results
+
+### Tests
+```
+✅ All 74 tests pass
+✅ No regressions introduced
+```
+
+### Bundle Size
+```
+✅ Minified: 3.34 KB
+✅ Gzipped: 1.30 KB
+✅ Budget: 5.00 KB (well under limit!)
+```
+
+## 🎯 Success Metrics Checklist
+
+- ✅ All main pages have complete meta tags and structured data
+- ✅ Navigation works with relative paths (compatible with sub-path deployments)
+- ✅ Sitemap and robots.txt created and accessible
+- ⏳ OG image template created (needs generation)
+- ✅ Active link highlighting logic fixed
+- ✅ Package.json optimized for npm
+- ✅ README enhanced with TOC and badges
+- ✅ GitHub topics updated for discoverability
+- ✅ Deployment documentation focuses on Cloudflare Pages
+- ⏳ Needs deployment and live testing
+
+## 📝 Next Steps
+
+1. **Generate og-image.png** from the template
+2. **Test locally** to verify navigation and SEO elements
+3. **Deploy to Cloudflare Pages** via `npm run deploy:cf:prod`
+4. **Verify live site** at https://frontjs.dev
+5. **Submit sitemap** to search engines
+6. **(Optional)** Add meta tags to individual example pages
+7. **(Optional)** Generate favicon.ico from favicon.svg
+
+## 🔗 Resources
+
+- **SEO Audit Document:** `notes/SEO optimization for front-js.docx.md`
+- **Implementation Plan:** Available via Warp plan system (ID: dbf0e86f-0111-444e-99f1-6d1620b908ca)
+- **OG Image Template:** `website/og-image-generator.html`
+- **Deployment Guide:** `DEVELOPMENT.md`

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "front-js",
+  "name": "@watthem/front-js",
   "version": "0.0.1",
   "description": "A lightweight (<5KB) secure-by-default JavaScript micro-framework enforcing Islands Architecture",
   "type": "module",
@@ -57,6 +57,10 @@
   "author": "Matthew Hendricks <matthew.scott.hendricks@gmail.com>",
   "homepage": "https://frontjs.dev",
   "license": "ISC",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
     "esbuild": "^0.19.0",
     "vitest": "^1.0.0",