@zenithbuild/core 0.1.0

package/assets/logos/README.md

@@ -0,0 +1,54 @@
+# Zenith Logos
+
+This directory contains the Zenith framework logo assets.
+
+## Logo Files
+
+Based on the logo designs, you should place the following files here:
+
+1. **zenith-logo-icon.png** (or .svg) - The file icon version with the folded corner and ".ZENITH" button
+2. **zenith-logo-z.png** (or .svg) - The stylized "Z" logo with gradient and light trails
+3. **zenith-logo-full.png** (or .svg) - The full logo with "ZENITH" text below
+4. **zenith-logo-soon.png** (or .svg) - The logo variant with "Soon" text
+
+## File Icon for .zen Files
+
+The SVG logo has been converted to a macOS `.icns` file to use as the file icon for `.zen` files.
+
+### Setting the Icon
+
+**Option 1: Use the automated script (recommended)**
+```bash
+cd assets/logos
+./set-zen-icon.sh path/to/your/file.zen
+```
+
+**Option 2: Set icon for all .zen files in a directory**
+```bash
+cd assets/logos
+find ../app -name "*.zen" -exec ./set-zen-icon.sh {} \;
+```
+
+**Option 3: Manual method**
+1. Open Finder and navigate to a `.zen` file
+2. Right-click the file and select "Get Info"
+3. Drag `zen.icns` onto the small icon in the top-left of the Get Info window
+4. Close the Get Info window
+
+### Recreating the .icns File
+
+If you update the SVG and need to regenerate the `.icns` file:
+```bash
+cd assets/logos
+./create-zen-icon.sh
+```
+
+## Usage
+
+These logos can be used in:
+- Documentation (`docs/`)
+- README files
+- Website/marketing materials
+- Framework branding
+- File type icons (`.zen` files)
+

package/bun.lock

@@ -0,0 +1,39 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "zenith",
+      "dependencies": {
+        "@types/parse5": "^7.0.0",
+        "parse5": "^8.0.0",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "prettier": "^3.7.4",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+
+    "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
+
+    "@types/parse5": ["@types/parse5@7.0.0", "", { "dependencies": { "parse5": "*" } }, "sha512-f2SeAxumolBmhuR62vNGTsSAvdz/Oj0k682xNrcKJ4dmRnTPODB74j6CPoNPzBPTHsu7Y7W7u93Mgp8Ovo8vWw=="],
+
+    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+
+    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
+
+    "parse5": ["parse5@8.0.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-9m4m5GSgXjL4AjumKzq1Fgfp3Z8rsvjRNbnkVwfu2ImRqE5D0LnY2QfDen18FSY9C573YU5XxSapdHZTZ2WolA=="],
+
+    "prettier": ["prettier@3.7.4", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/compiler/README.md

@@ -0,0 +1,380 @@
+# Zenith Compiler - Phase 1: Parse & Extract
+
+## Overview
+
+This is Phase 1 of the Zenith compiler implementation. This phase focuses on **parsing and extracting** structure from `.zen` files without any runtime execution or transformation.
+
+## Directory Structure
+
+```
+/compiler
+  /parse
+    parseZenFile.ts    # Main file parser
+    parseTemplate.ts   # Template/HTML parser
+    parseScript.ts     # Script block extractor
+  /ir
+    types.ts           # Intermediate Representation types
+  /errors
+    compilerError.ts   # Compiler error handling
+  index.ts             # Public API entry point
+```
+
+## Usage
+
+```typescript
+import { compileZen } from './compiler/index'
+
+const ir = compileZen('app/pages/example.zen')
+// Returns ZenIR structure with parsed template, script, styles, and extracted expressions
+```
+
+## What This Phase Does
+
+✅ Parses `.zen` files into structured IR
+✅ Extracts `<script>` and `<style>` blocks
+✅ Parses HTML template structure
+✅ Extracts `{expression}` patterns from text and attributes
+✅ Records source locations for all nodes and expressions
+✅ Throws compiler errors with location information
+
+## What This Phase Does NOT Do
+
+❌ Execute expressions
+❌ Transform code
+❌ Generate runtime code
+❌ Handle reactivity
+❌ Render to DOM
+❌ Perform any runtime operations
+
+## IR Structure
+
+The compiler produces a `ZenIR` object containing:
+
+- `filePath`: Path to the source file
+- `template`: TemplateIR with nodes and extracted expressions
+- `script`: ScriptIR with raw script content (or null)
+- `styles`: Array of StyleIR with raw style content
+
+## Expression Extraction
+
+Expressions are extracted from:
+- Text content: `Hello {name}!`
+- Attribute values: `class={isActive ? "on" : "off"}`
+
+Each expression gets:
+- Unique ID (e.g., `expr_0`, `expr_1`)
+- Source code (the expression content)
+- Source location (line + column)
+
+## Phase 2: Transform IR → Static HTML + Runtime Bindings
+
+Phase 2 transforms the IR into static HTML with explicit bindings:
+
+- ✅ All `{}` expressions removed from HTML
+- ✅ Expressions replaced with data attributes (`data-zen-text`, `data-zen-attr-*`)
+- ✅ Bindings array generated with expression source code
+- ✅ Scripts and styles pass through unchanged
+- ✅ No runtime execution - pure transformation
+
+### Output Structure
+
+```typescript
+{
+  html: string,        // Static HTML with no {}
+  bindings: Binding[], // Array of expression bindings
+  scripts: string,     // Raw script content
+  styles: string[]     // Raw style content
+}
+```
+
+### Binding Format
+
+```typescript
+{
+  id: "exp_1",
+  type: "text" | "attribute",
+  target: "data-zen-text" | "class" | "style" | etc,
+  expression: "user.name" // Original expression code
+}
+```
+
+## Phase 4: Runtime DOM & Reactivity
+
+Phase 4 transforms the IR into fully functional runtime JavaScript code:
+
+- ✅ Expression wrapping with state access
+- ✅ DOM creation code generation
+- ✅ Event handler binding
+- ✅ State initialization
+- ✅ Hydrate function for SPA hydration
+- ✅ Style injection
+
+### Runtime Code Structure
+
+```typescript
+{
+  expressions: string,  // Wrapped expression functions
+  render: string,       // renderDynamicPage(state) function
+  hydrate: string,      // hydrate(root, state) function
+  styles: string,       // Style injection code
+  script: string,       // Transformed script code
+  stateInit: string     // State initialization code
+}
+```
+
+### Usage
+
+```typescript
+import { compileZen } from './compiler/index'
+import { transformIR } from './compiler/runtime/transformIR'
+
+const { ir } = compileZen('app/pages/example.zen')
+const runtime = transformIR(ir)
+
+// Runtime code is now ready to execute
+// - runtime.expressions: Expression wrapper functions
+// - runtime.render: DOM creation function
+// - runtime.hydrate: Hydration function
+```
+
+## Phase 5: Runtime Hydration
+
+Phase 5 provides the browser-side runtime that hydrates static HTML with dynamic expressions:
+
+- ✅ Expression evaluation via registry (`window.__ZENITH_EXPRESSIONS__`)
+- ✅ Text binding updates (`data-zen-text` attributes)
+- ✅ Attribute binding updates (`data-zen-attr-*` attributes)
+- ✅ Event handler binding (`data-zen-{eventType}` attributes)
+- ✅ Reactive state updates (`update(state)` function)
+- ✅ Cleanup and memory management
+- ✅ Error handling with expression IDs
+
+### Runtime Functions
+
+```typescript
+// Hydrate static HTML with dynamic expressions
+window.zenithHydrate(state, container?)
+
+// Update all bindings when state changes
+window.zenithUpdate(state)
+
+// Bind event handlers
+window.zenithBindEvents(container?)
+
+// Cleanup bindings and event listeners
+window.zenithCleanup(container?)
+```
+
+### Runtime Bundle
+
+The `transformIR` function now generates a complete runtime bundle:
+
+```typescript
+const runtime = transformIR(ir)
+// runtime.bundle contains the complete JavaScript code ready for browser execution
+```
+
+The bundle includes:
+- Expression wrapper functions
+- Expression registry initialization
+- Hydration runtime code
+- State initialization
+- Style injection
+- User script code
+
+### Usage Example
+
+```typescript
+// In browser
+const state = { user: { name: 'Alice' }, count: 5 }
+window.zenithHydrate(state, document.body)
+
+// On state change
+state.count = 10
+window.zenithUpdate(state)
+```
+
+## Phase 6: Explicit Data Exposure
+
+Phase 6 ensures all data references are explicit rather than relying on implicit globals:
+
+- ✅ Expression dependency analysis (loaderData, props, stores, state)
+- ✅ Explicit function signatures with data arguments
+- ✅ Updated hydration runtime to pass explicit data
+- ✅ Compile-time validation of data references
+- ✅ Backwards compatibility with legacy state-only expressions
+
+### Data Sources
+
+Expressions can reference data from:
+1. **Loader Data** - Route-level `loader()` function data (`loaderData.user.name`)
+2. **Props** - Component/page props (`props.title`)
+3. **Stores** - Global stores (`stores.cart.items`)
+4. **State** - Reactive state (`state.count`)
+
+### Expression Wrapper Signatures
+
+Phase 6 expressions now accept explicit arguments:
+
+```typescript
+// Before (Phase 5)
+const expr_0 = (state) => { with (state) { return user.name } }
+
+// After (Phase 6)
+const expr_0 = (state, loaderData, props, stores) => {
+  const __ctx = Object.assign({}, loaderData, props, stores, state);
+  with (__ctx) { return user.name }
+}
+```
+
+### Runtime Hydration
+
+```typescript
+// Phase 6 signature
+window.zenithHydrate(state, loaderData, props, stores, container?)
+window.zenithUpdate(state, loaderData, props, stores)
+```
+
+The runtime maintains backwards compatibility - if called with only `state`, it uses legacy behavior.
+
+### Data Dependency Analysis
+
+The compiler analyzes each expression to detect:
+- `loaderData.property` → loader data dependency
+- `props.name` → props dependency
+- `stores.name` → stores dependency
+- Simple identifiers → state dependency
+
+All dependencies are validated at compile time with clear error messages.
+
+## Phase 7: Navigation, Prefetch & Bun Accelerator
+
+Phase 7 implements safe SPA navigation with prefetching and explicit data exposure:
+
+- ✅ Prefetch compiled output (HTML + JS) for routes
+- ✅ Route caching system
+- ✅ Safe SPA navigation with explicit data (loaderData, props, stores)
+- ✅ Browser history handling (back/forward)
+- ✅ ZenLink component with prefetch support
+- ✅ Navigation runtime integration
+- ✅ No raw .zen files in browser
+
+### Navigation API
+
+```typescript
+// Prefetch a route
+window.__zenith_prefetch('/dashboard')
+
+// Navigate with explicit data
+window.navigate('/dashboard', {
+  loaderData: { user: { name: 'Alice' } },
+  props: { title: 'Dashboard' },
+  stores: { cart: { items: 3 } },
+  replace: false  // Use pushState instead of replaceState
+})
+```
+
+### ZenLink Component
+
+```html
+<!-- With prefetch (on hover) -->
+<ZenLink href="/about" prefetch={true}>About</ZenLink>
+
+<!-- Without prefetch -->
+<ZenLink href="/blog">Blog</ZenLink>
+```
+
+### Key Principles
+
+1. **Compiler owns all expressions** - Runtime never parses .zen files
+2. **Prefetch compiled output** - HTML + JS bundles, not source
+3. **Explicit data exposure** - All data passed explicitly (no implicit globals)
+4. **Bun as accelerator** - Used for bundling/transpilation, not template parsing
+5. **Safe navigation** - No stacked mutations, proper cleanup, history handling
+
+### Route Cache
+
+Prefetched routes are cached with:
+- Compiled HTML
+- Compiled JS runtime
+- Styles
+- Route metadata
+
+### Browser History
+
+The navigation system:
+- Handles `popstate` events for back/forward
+- Updates DOM safely without re-parsing
+- Maintains route state correctly
+- Avoids stacked history mutations
+
+## Phase 8/9/10: Finalization & Build Guarantees
+
+Phase 8/9/10 ensures deterministic compilation and compile-time validation:
+
+- ✅ Compile-time expression validation
+- ✅ Build fails on invalid expressions with line/column info
+- ✅ No raw `{expression}` in HTML output
+- ✅ Thin declarative runtime (no eval, no template parsing)
+- ✅ Bun integration for bundling/transpilation (not template parsing)
+- ✅ Final HTML + JS output ready for browser
+
+### Validation
+
+All expressions are validated at compile time:
+- Syntax validation
+- Brace/parentheses/bracket matching
+- Unsafe code detection (eval, Function, with)
+- Build fails immediately on errors
+
+### Output Guarantees
+
+- **HTML**: Contains only hydration markers (`data-zen-text`, `data-zen-attr-*`)
+- **JS**: Pre-compiled expression functions, no template parsing
+- **Runtime**: Thin, declarative - only DOM updates and event binding
+- **No eval**: Runtime never uses `eval`, `new Function`, or `with(window)`
+
+### Bun Integration
+
+Bun is used as an accelerator for:
+- ✅ JS/TS transpilation
+- ✅ Asset bundling
+- ✅ SSR runtime support
+
+Bun is **NOT** used for:
+- ❌ Template parsing
+- ❌ Expression analysis
+- ❌ AST transformations
+
+### Build Guarantees
+
+- Build success = UI guaranteed to work
+- All failures are compile-time (never runtime)
+- Error messages include file, line, column
+- Invalid expressions fail the build immediately
+
+## Next Phases
+
+Future enhancements:
+- Enhanced conditional/ternary handling in IR
+- Map iteration support in IR
+- Advanced reactivity with dependency tracking
+- SSR/SSG/ISR output generation
+- Type checking for loader/props/stores data
+- Route cache generation in build system
+
+## Testing
+
+The compiler can be tested by importing and calling `compileZen()`:
+
+```typescript
+import { compileZen } from './compiler/index'
+
+try {
+  const ir = compileZen('app/pages/example.zen')
+  console.log(JSON.stringify(ir, null, 2))
+} catch (error) {
+  console.error('Compiler error:', error)
+}
+```
+

package/compiler/errors/compilerError.ts

@@ -0,0 +1,24 @@
+/**
+ * Compiler Error Handling
+ * 
+ * Compiler errors with source location information
+ */
+
+export class CompilerError extends Error {
+  file: string
+  line: number
+  column: number
+
+  constructor(message: string, file: string, line: number, column: number) {
+    super(`${file}:${line}:${column} ${message}`)
+    this.name = 'CompilerError'
+    this.file = file
+    this.line = line
+    this.column = column
+  }
+
+  override toString(): string {
+    return `${this.file}:${this.line}:${this.column} ${this.message}`
+  }
+}
+

package/compiler/finalize/finalizeOutput.ts

@@ -0,0 +1,163 @@
+/**
+ * Finalize Output
+ * 
+ * Phase 8/9/10: Generate final compiled HTML + JS output with hydration markers
+ * 
+ * Ensures:
+ * - All expressions are replaced with hydration markers
+ * - HTML contains no raw {expression} syntax
+ * - JS runtime is ready for browser execution
+ * - Hydration markers are correctly placed
+ */
+
+import type { CompiledTemplate } from '../output/types'
+import type { ZenIR } from '../ir/types'
+import { transformIR, type RuntimeCode } from '../runtime/transformIR'
+import { validateExpressionsOrThrow } from '../validate/validateExpressions'
+
+/**
+ * Finalized output ready for browser
+ */
+export interface FinalizedOutput {
+  html: string
+  js: string
+  styles: string[]
+  hasErrors: boolean
+  errors: string[]
+}
+
+/**
+ * Finalize compiler output
+ * 
+ * This is the final step that ensures:
+ * 1. All expressions are validated
+ * 2. HTML contains no raw expressions
+ * 3. JS runtime is generated
+ * 4. Output is ready for browser
+ * 
+ * @param ir - Intermediate representation
+ * @param compiled - Compiled template from Phase 2
+ * @returns Finalized output
+ */
+export function finalizeOutput(
+  ir: ZenIR,
+  compiled: CompiledTemplate
+): FinalizedOutput {
+  const errors: string[] = []
+
+  // 1. Validate all expressions (Phase 8/9/10 requirement)
+  try {
+    validateExpressionsOrThrow(ir.template.expressions, ir.filePath)
+  } catch (error: any) {
+    if (error instanceof Error) {
+      errors.push(error.message)
+      return {
+        html: '',
+        js: '',
+        styles: [],
+        hasErrors: true,
+        errors
+      }
+    }
+  }
+
+  // 2. Verify HTML contains no raw expressions
+  const htmlErrors = verifyNoRawExpressions(compiled.html, ir.filePath)
+  if (htmlErrors.length > 0) {
+    errors.push(...htmlErrors)
+    return {
+      html: '',
+      js: '',
+      styles: [],
+      hasErrors: true,
+      errors
+    }
+  }
+
+  // 3. Generate runtime code
+  let runtimeCode: RuntimeCode
+  try {
+    runtimeCode = transformIR(ir)
+  } catch (error: any) {
+    errors.push(`Runtime generation failed: ${error.message}`)
+    return {
+      html: '',
+      js: '',
+      styles: [],
+      hasErrors: true,
+      errors
+    }
+  }
+
+  // 4. Combine HTML and JS
+  const finalHTML = compiled.html
+  const finalJS = runtimeCode.bundle
+
+  return {
+    html: finalHTML,
+    js: finalJS,
+    styles: compiled.styles,
+    hasErrors: false,
+    errors: []
+  }
+}
+
+/**
+ * Verify HTML contains no raw {expression} syntax
+ * 
+ * This is a critical check - browser must never see raw expressions
+ */
+function verifyNoRawExpressions(html: string, filePath: string): string[] {
+  const errors: string[] = []
+  
+  // Check for raw {expression} patterns (not data-zen-* attributes)
+  // Allow data-zen-text, data-zen-attr-* but not raw { }
+  const rawExpressionPattern = /\{[^}]*\}/g
+  const matches = html.match(rawExpressionPattern)
+  
+  if (matches && matches.length > 0) {
+    // Filter out false positives (comments, data attributes, etc.)
+    const actualExpressions = matches.filter(match => {
+      // Exclude if it's in a comment
+      if (html.includes(`<!--${match}`) || html.includes(`${match}-->`)) {
+        return false
+      }
+      // Exclude if it's in a data attribute value (already processed)
+      if (match.includes('data-zen-')) {
+        return false
+      }
+      // This looks like a raw expression
+      return true
+    })
+    
+    if (actualExpressions.length > 0) {
+      errors.push(
+        `HTML contains raw expressions that were not compiled: ${actualExpressions.join(', ')}\n` +
+        `File: ${filePath}\n` +
+        `All expressions must be replaced with hydration markers (data-zen-text, data-zen-attr-*)`
+      )
+    }
+  }
+  
+  return errors
+}
+
+/**
+ * Generate final output with error handling
+ * 
+ * Throws if validation fails (build must fail on errors)
+ */
+export function finalizeOutputOrThrow(
+  ir: ZenIR,
+  compiled: CompiledTemplate
+): FinalizedOutput {
+  const output = finalizeOutput(ir, compiled)
+  
+  if (output.hasErrors) {
+    const errorMessage = output.errors.join('\n\n')
+    throw new Error(`Compilation failed:\n\n${errorMessage}`)
+  }
+  
+  return output
+}
+