@zenithbuild/core 0.1.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# 💫 Contributing to Zenith
+## 📌 Prerequisites
+
+> Before you begin, join the [Discord Server](https://discord.gg/T85bBj8T3n) and **ensure you have the following installed**:
+
+- **[Bun](https://bun.sh/)** (v1.0 or later) - Zenith uses Bun as its JavaScript runtime and package manager
+- **[Git](https://git-scm.com/)** - For version control
+
+### Installation
+
+1. **Clone the repository (no fork)**
+   ```ts
+   git clone https://github.com/judahbsullivan/zenith.js.git
+   cd zenith
+   ```
+2. **Install dependencies**
+   ```ts
+   bun install
+   ```
+3. **Build the application** (required first)
+   ```ts
+   bun run build
+   ```
+   This compiles `.zen` files from `app/pages/` into `app/dist/`.
+
+4. **Run the development server**
+   ```ts
+   bun run dev
+
+> **Important**: Use `bun run <script>` to execute npm scripts from package.json. The command `bun build` (without `run`) invokes Bun's built-in bundler, which won't specify our entrypoints by default.
+
+## 🌿 Branching Strategy
+### Option 1: Issue-Driven Development (Preferred)
+
+1. **Create or find an issue** on GitHub that describes the work you want to do
+2. **Create a branch from the issue** directly on GitHub
+   - Branch name format: `{issue-number}-{short-description}`
+   - Example: `33-contributing-md`
+3. **Pull the branch** to your local machine
+   ```ts
+   git fetch origin
+   git checkout 33-contributing-md
+   ```
+
+### Option 2: Feature/Fix Branch
+
+If you're working on something without an existing issue:
+
+1. **Branch from `main`**
+   ```ts
+   git checkout main
+   git pull origin main
+   git checkout -b {prefix}/{short-description}
+   ```
+2. **Use appropriate prefix subfolder** based on the type of change:
+   - `feat/` for new features → MINOR version bump (0.n.0)
+   - `fix/` for bug fixes → PATCH version bump (0.0.n)
+   - `docs/` for documentation changes
+   - `refactor/` for code refactoring
+   - `test/` for adding or updating tests
+   - `chore/` for maintenance tasks
+
+Example: `feat/reactive-state` or `fix/router-navigation`
+
+## 📝 Commit Strategy
+> Zenith follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for consistent versioning and changelog generation.
+
+### Commit Message Format
+
+```ts
+<type>[optional scope]: <description>
+[optional body]
+[optional footer(s)]
+```
+### Quick Reference
+
+| Prefix   | SemVer Impact | Example                          |
+|----------|---------------|----------------------------------|
+| `fix:`   | PATCH (0.0.n) | `fix: html not recognizing state` |
+| `feat:`  | MINOR (0.n.0) | `feat: add reactive state system` |
+| `feat!:` | MAJOR (n.0.0) | `feat!: change compiler API`      |
+| `fix!:`  | MAJOR (n.0.0) | `fix!: remove deprecated methods` |
+
+**Breaking Changes**: Use `!` after the type or include `BREAKING CHANGE:` in the footer.
+
+**📌 For complete details, see [COMMITS.md](COMMITS.md)**
+
+## 💬 Pull Request Comment Strategy
+> Zenith uses [Conventional Comments](https://conventionalcomments.org/) for clear, actionable PR feedback.
+
+### Comment Format
+```ts
+<label> [decorations]: <subject>
+[discussion]
+```
+### Examples
+```ts
+suggestion (non-blocking): Consider using a more descriptive variable name
+This would improve readability for future maintainers.
+```
+```ts
+issue (blocking): This function will throw an error when input is null
+We need to add null checking before processing.
+```
+
+**📌 For complete details, see [COMMENTS.md](COMMENTS.md)**
+
+## ❓ Questions?
+- Check existing [Issues](https://github.com/judahbsullivan/zenith/issues)
+- Review [README.md](../README.md) for project overview
+- Reach out to maintainers in your PR, Issue or [Discord!](https://discord.gg/T85bBj8T3n)
+
+---
+
+**Remember**: Contributing should be enjoyable! Don't hesitate to ask questions if anything is unclear.
+

package/docs/STYLEGUIDE.md

@@ -0,0 +1,62 @@
+# Style Guide
+## Code Style
+- TypeScript only
+- No implicit any
+- Prefer explicit return types for public APIs
+- Avoid magic strings
+## Architectural Rules
+- Compiler decisions > runtime decisions
+- HTML is the source of truth
+- Navigation controls rendering, not components
+- Layouts persist unless explicitly changed
+## Naming Conventions
+- camelCase for variables
+- PascalCase for components
+- kebab-case for files where appropriate
+- `.zenith` for user-facing components
+## API Design Rules
+- No developer flags for runtime behavior
+- Behavior inferred via static analysis
+- Fail loudly at compile time
+## What to Avoid
+- Implicit global state
+- Hidden hydration logic
+- Runtime heuristics
+- JSX-only APIs
+## Guiding Question
+> "Can the compiler decide this instead?"
+If yes — move it out of runtime.
+
+## 🎯 Development Philosophy
+
+- **Simplicity over complexity** - Zenith aims to be intuitive and straightforward
+- **HTML-first** - HTML is the source of truth
+- **Consistency** - Follow established patterns in the codebase
+- **Iteration speed** - Don't let perfect be the enemy of good
+
+## 🧪 Testing Your Changes
+
+Before submitting a PR:
+
+1. **Build the application** to compile your changes:
+   ```bash
+   bun run build
+   ```
+
+2. **Run the dev server** and verify your changes work:
+   ```bash
+   bun run dev
+   ```
+   Visit `http://localhost:3000` to test.
+
+3. **Format your code**:
+   ```bash
+   bun run format
+   ```
+
+4. **Check formatting** (optional):
+   ```bash
+   bun run format:check
+   ```
+
+> **Note**: Use `bun run <script>` for npm scripts. Plain `bun build` invokes Bun's bundler, not the project build script.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@zenithbuild/core",
+  "version": "0.1.0",
+  "description": "Core library for the Zenith framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./compiler": "./compiler/index.ts",
+    "./core": "./core/index.ts",
+    "./router": "./router/index.ts",
+    "./runtime": "./runtime/index.ts"
+  },
+  "keywords": [
+    "zenith",
+    "core",
+    "framework"
+  ],
+  "author": "Zenith Team",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:zenithbuild/zenith-core.git"
+  },
+  "scripts": {
+    "dev": "bun dev",
+    "build": "bun build",
+    "start": "bun run build && bun run dev",
+    "format": "prettier --write \"**/*.ts\"",
+    "format:check": "prettier --check \"**/*.ts\""
+  },
+  "private": false,
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.7.4"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@types/parse5": "^7.0.0",
+    "parse5": "^8.0.0"
+  }
+}

package/router/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Zenith Router
+ * 
+ * File-based SPA router for Zenith framework.
+ * Includes routing, navigation, and ZenLink components.
+ * 
+ * @example
+ * ```ts
+ * import { navigate, isActive, prefetch } from 'zenith/router'
+ * 
+ * // Navigate programmatically
+ * navigate('/about')
+ * 
+ * // Check active state
+ * if (isActive('/blog')) {
+ *   console.log('On blog section')
+ * }
+ * ```
+ */
+
+// Core router types and utilities
+export * from "./types"
+export * from "./manifest"
+
+// Router runtime (core router implementation)
+// These are the primary exports for router functionality
+export {
+  initRouter,
+  resolveRoute,
+  navigate,
+  getRoute,
+  onRouteChange,
+  beforeEach,
+  afterEach,
+  isActive,
+  prefetch,
+  isPrefetched
+} from "./runtime"
+
+// Navigation utilities (additional helpers and zen* prefixed exports)
+// Note: Some functions like navigate, isActive, prefetch are also in runtime
+// We export runtime's versions above, and navigation's unique functions here
+export {
+  // Navigation API (zen* prefixed names)
+  zenNavigate,
+  zenBack,
+  zenForward,
+  zenGo,
+  zenIsActive,
+  zenPrefetch,
+  zenIsPrefetched,
+  zenGetRoute,
+  zenGetParam,
+  zenGetQuery,
+  createZenLink,
+  zenLink,
+  // Additional navigation utilities (not in runtime)
+  back,
+  forward,
+  go,
+  getParam,
+  getQuery,
+  isExternalUrl,
+  shouldUseSPANavigation,
+  normalizePath,
+  setGlobalTransition,
+  getGlobalTransition,
+  createTransitionContext
+} from "./navigation/index"
+
+// Navigation-specific types
+export type {
+  ZenLinkProps,
+  TransitionContext,
+  TransitionHandler
+} from "./navigation/index"

package/router/manifest.ts

@@ -0,0 +1,314 @@
+/**
+ * Zenith Route Manifest Generator
+ * 
+ * Scans pages/ directory at build time and generates a route manifest
+ * with proper scoring for deterministic route matching.
+ */
+
+import fs from "fs"
+import path from "path"
+import {
+  type RouteDefinition,
+  type ParsedSegment,
+  SegmentType
+} from "./types"
+
+/**
+ * Scoring constants for route ranking
+ * Higher scores = higher priority
+ */
+const SEGMENT_SCORES = {
+  [SegmentType.STATIC]: 10,
+  [SegmentType.DYNAMIC]: 5,
+  [SegmentType.CATCH_ALL]: 1,
+  [SegmentType.OPTIONAL_CATCH_ALL]: 0
+} as const
+
+/**
+ * Discover all .zen files in the pages directory
+ */
+export function discoverPages(pagesDir: string): string[] {
+  const pages: string[] = []
+  
+  function walk(dir: string): void {
+    if (!fs.existsSync(dir)) return
+    
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+      
+      if (entry.isDirectory()) {
+        walk(fullPath)
+      } else if (entry.isFile() && entry.name.endsWith(".zen")) {
+        pages.push(fullPath)
+      }
+    }
+  }
+  
+  walk(pagesDir)
+  return pages
+}
+
+/**
+ * Convert a file path to a route path
+ * 
+ * Examples:
+ *   pages/index.zen       → /
+ *   pages/about.zen       → /about
+ *   pages/blog/index.zen  → /blog
+ *   pages/blog/[id].zen   → /blog/:id
+ *   pages/posts/[...slug].zen → /posts/*slug
+ *   pages/[[...all]].zen  → /*all (optional)
+ */
+export function filePathToRoutePath(filePath: string, pagesDir: string): string {
+  // Get relative path from pages directory
+  const relativePath = path.relative(pagesDir, filePath)
+  
+  // Remove .zen extension
+  const withoutExt = relativePath.replace(/\.zen$/, "")
+  
+  // Split into segments
+  const segments = withoutExt.split(path.sep)
+  
+  // Transform segments
+  const routeSegments: string[] = []
+  
+  for (const segment of segments) {
+    // Handle index files (they represent the directory root)
+    if (segment === "index") {
+      continue
+    }
+    
+    // Handle optional catch-all: [[...param]]
+    const optionalCatchAllMatch = segment.match(/^\[\[\.\.\.(\w+)\]\]$/)
+    if (optionalCatchAllMatch) {
+      routeSegments.push(`*${optionalCatchAllMatch[1]}?`)
+      continue
+    }
+    
+    // Handle required catch-all: [...param]
+    const catchAllMatch = segment.match(/^\[\.\.\.(\w+)\]$/)
+    if (catchAllMatch) {
+      routeSegments.push(`*${catchAllMatch[1]}`)
+      continue
+    }
+    
+    // Handle dynamic segment: [param]
+    const dynamicMatch = segment.match(/^\[(\w+)\]$/)
+    if (dynamicMatch) {
+      routeSegments.push(`:${dynamicMatch[1]}`)
+      continue
+    }
+    
+    // Static segment
+    routeSegments.push(segment)
+  }
+  
+  // Build route path
+  const routePath = "/" + routeSegments.join("/")
+  
+  // Normalize trailing slashes
+  return routePath === "/" ? "/" : routePath.replace(/\/$/, "")
+}
+
+/**
+ * Parse a route path into segments with type information
+ */
+export function parseRouteSegments(routePath: string): ParsedSegment[] {
+  if (routePath === "/") {
+    return []
+  }
+  
+  const segments = routePath.slice(1).split("/")
+  const parsed: ParsedSegment[] = []
+  
+  for (const segment of segments) {
+    // Optional catch-all: *param?
+    if (segment.startsWith("*") && segment.endsWith("?")) {
+      parsed.push({
+        type: SegmentType.OPTIONAL_CATCH_ALL,
+        paramName: segment.slice(1, -1),
+        raw: segment
+      })
+      continue
+    }
+    
+    // Required catch-all: *param
+    if (segment.startsWith("*")) {
+      parsed.push({
+        type: SegmentType.CATCH_ALL,
+        paramName: segment.slice(1),
+        raw: segment
+      })
+      continue
+    }
+    
+    // Dynamic: :param
+    if (segment.startsWith(":")) {
+      parsed.push({
+        type: SegmentType.DYNAMIC,
+        paramName: segment.slice(1),
+        raw: segment
+      })
+      continue
+    }
+    
+    // Static
+    parsed.push({
+      type: SegmentType.STATIC,
+      raw: segment
+    })
+  }
+  
+  return parsed
+}
+
+/**
+ * Calculate route score based on segments
+ * Higher scores = higher priority for matching
+ */
+export function calculateRouteScore(segments: ParsedSegment[]): number {
+  if (segments.length === 0) {
+    // Root route gets a high score
+    return 100
+  }
+  
+  let score = 0
+  
+  for (const segment of segments) {
+    score += SEGMENT_SCORES[segment.type]
+  }
+  
+  // Bonus for having more static segments (specificity)
+  const staticCount = segments.filter(s => s.type === SegmentType.STATIC).length
+  score += staticCount * 2
+  
+  return score
+}
+
+/**
+ * Extract parameter names from parsed segments
+ */
+export function extractParamNames(segments: ParsedSegment[]): string[] {
+  return segments
+    .filter(s => s.paramName !== undefined)
+    .map(s => s.paramName!)
+}
+
+/**
+ * Convert route path to regex pattern
+ * 
+ * Examples:
+ *   /about         → /^\/about\/?$/
+ *   /blog/:id      → /^\/blog\/([^/]+)\/?$/
+ *   /posts/*slug   → /^\/posts\/(.+)\/?$/
+ *   /              → /^\/$/
+ *   /*all?         → /^(?:\/(.*))?$/  (optional catch-all)
+ */
+export function routePathToRegex(routePath: string): RegExp {
+  if (routePath === "/") {
+    return /^\/$/
+  }
+  
+  const segments = routePath.slice(1).split("/")
+  const regexParts: string[] = []
+  
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    if (!segment) continue
+    
+    // Optional catch-all: *param?
+    if (segment.startsWith("*") && segment.endsWith("?")) {
+      // Optional catch-all - matches zero or more path segments
+      // Should only be at the end
+      regexParts.push("(?:\\/(.*))?")
+      continue
+    }
+    
+    // Required catch-all: *param
+    if (segment.startsWith("*")) {
+      // Required catch-all - matches one or more path segments
+      regexParts.push("\\/(.+)")
+      continue
+    }
+    
+    // Dynamic: :param
+    if (segment.startsWith(":")) {
+      regexParts.push("\\/([^/]+)")
+      continue
+    }
+    
+    // Static segment - escape special regex characters
+    const escaped = segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    regexParts.push(`\\/${escaped}`)
+  }
+  
+  // Build final regex with optional trailing slash
+  const pattern = `^${regexParts.join("")}\\/?$`
+  return new RegExp(pattern)
+}
+
+/**
+ * Generate a route definition from a file path
+ */
+export function generateRouteDefinition(
+  filePath: string,
+  pagesDir: string
+): RouteDefinition {
+  const routePath = filePathToRoutePath(filePath, pagesDir)
+  const segments = parseRouteSegments(routePath)
+  const paramNames = extractParamNames(segments)
+  const score = calculateRouteScore(segments)
+  
+  return {
+    path: routePath,
+    segments,
+    paramNames,
+    score,
+    filePath
+  }
+}
+
+/**
+ * Generate route manifest from pages directory
+ * Returns route definitions sorted by score (highest first)
+ */
+export function generateRouteManifest(pagesDir: string): RouteDefinition[] {
+  const pages = discoverPages(pagesDir)
+  
+  const definitions = pages.map(filePath => 
+    generateRouteDefinition(filePath, pagesDir)
+  )
+  
+  // Sort by score descending (highest priority first)
+  definitions.sort((a, b) => b.score - a.score)
+  
+  return definitions
+}
+
+/**
+ * Generate the route manifest as JavaScript code for runtime
+ */
+export function generateRouteManifestCode(definitions: RouteDefinition[]): string {
+  const routeEntries = definitions.map(def => {
+    const regex = routePathToRegex(def.path)
+    
+    return `  {
+    path: ${JSON.stringify(def.path)},
+    regex: ${regex.toString()},
+    paramNames: ${JSON.stringify(def.paramNames)},
+    score: ${def.score},
+    filePath: ${JSON.stringify(def.filePath)}
+  }`
+  })
+  
+  return `// Auto-generated route manifest
+// Do not edit directly
+
+export const routeManifest = [
+${routeEntries.join(",\n")}
+];
+`
+}
+