@zenithbuild/core 0.1.0

package/core/reactivity/zen-memo.ts

@@ -0,0 +1,146 @@
+/**
+ * Zenith Memo - Computed/Derived Value
+ * 
+ * A memo is a lazily-evaluated, cached computation that automatically
+ * tracks its dependencies and only recomputes when those dependencies change.
+ * 
+ * Features:
+ * - Lazy evaluation (only computes when read)
+ * - Automatic dependency tracking
+ * - Cached value until dependencies change
+ * - Read-only (no setter)
+ * 
+ * @example
+ * ```ts
+ * const firstName = zenSignal('John')
+ * const lastName = zenSignal('Doe')
+ * 
+ * // Memo computes full name, tracks firstName and lastName
+ * const fullName = zenMemo(() => `${firstName()} ${lastName()}`)
+ * 
+ * console.log(fullName()) // "John Doe"
+ * 
+ * firstName('Jane')
+ * console.log(fullName()) // "Jane Doe" (recomputed)
+ * console.log(fullName()) // "Jane Doe" (cached, no recomputation)
+ * ```
+ */
+
+import {
+  pushContext,
+  popContext,
+  cleanupContext,
+  trackDependency,
+  type TrackingContext,
+  type Subscriber
+} from './tracking'
+
+/**
+ * Memo interface - callable getter
+ */
+export interface Memo<T> {
+  /** Get the current computed value */
+  (): T
+  /** Peek at cached value without tracking (may be stale) */
+  peek(): T
+}
+
+/**
+ * Memo state
+ */
+interface MemoState<T> {
+  /** The computation function */
+  fn: () => T
+  /** Cached value */
+  value: T | undefined
+  /** Whether the cached value is valid */
+  dirty: boolean
+  /** Tracking context for dependency collection */
+  context: TrackingContext
+  /** Subscribers to this memo */
+  subscribers: Set<Subscriber>
+  /** Whether this is the first computation */
+  initialized: boolean
+}
+
+/**
+ * Create a memoized computed value
+ * 
+ * @param fn - The computation function
+ * @returns A memo that can be read to get the computed value
+ */
+export function zenMemo<T>(fn: () => T): Memo<T> {
+  const state: MemoState<T> = {
+    fn,
+    value: undefined,
+    dirty: true,
+    context: {
+      execute: () => markDirty(state),
+      dependencies: new Set()
+    },
+    subscribers: new Set(),
+    initialized: false
+  }
+  
+  function memo(): T {
+    // Track that something is reading this memo
+    trackDependency(state.subscribers)
+    
+    // Recompute if dirty
+    if (state.dirty) {
+      computeMemo(state)
+    }
+    
+    return state.value as T
+  }
+  
+  // Add peek method
+  ;(memo as Memo<T>).peek = function(): T {
+    // Return cached value without tracking or recomputing
+    if (state.dirty && !state.initialized) {
+      computeMemo(state)
+    }
+    return state.value as T
+  }
+  
+  return memo as Memo<T>
+}
+
+/**
+ * Compute the memo value, tracking dependencies
+ */
+function computeMemo<T>(state: MemoState<T>): void {
+  // Clean up old dependencies
+  cleanupContext(state.context)
+  
+  // Push this memo onto the tracking stack
+  pushContext(state.context)
+  
+  try {
+    // Compute new value
+    state.value = state.fn()
+    state.dirty = false
+    state.initialized = true
+  } finally {
+    // Pop from tracking stack
+    popContext()
+  }
+}
+
+/**
+ * Mark the memo as dirty (needs recomputation)
+ * Called when a dependency changes
+ */
+function markDirty<T>(state: MemoState<T>): void {
+  if (!state.dirty) {
+    state.dirty = true
+    
+    // Notify any effects/memos that depend on this memo
+    // Copy to avoid issues during iteration
+    const subscribers = [...state.subscribers]
+    for (const subscriber of subscribers) {
+      subscriber()
+    }
+  }
+}
+

package/core/reactivity/zen-ref.ts

@@ -0,0 +1,52 @@
+/**
+ * Zenith Ref - Mutable Reference Container
+ * 
+ * A ref is a mutable container that does NOT trigger reactivity.
+ * It's useful for:
+ * - Storing DOM element references
+ * - Imperative escape hatches
+ * - Values that change but shouldn't trigger re-renders
+ * 
+ * Features:
+ * - Mutable `.current` property
+ * - Does NOT track dependencies
+ * - Does NOT trigger effects
+ * - Persists across effect re-runs
+ * 
+ * @example
+ * ```ts
+ * // DOM reference
+ * const inputRef = zenRef<HTMLInputElement>()
+ * 
+ * // Later, after mount
+ * inputRef.current = document.querySelector('input')
+ * inputRef.current?.focus()
+ * 
+ * // Mutable value that doesn't trigger reactivity
+ * const previousValue = zenRef(0)
+ * previousValue.current = count() // No effect triggered
+ * ```
+ */
+
+/**
+ * Ref interface - mutable container with .current
+ */
+export interface Ref<T> {
+  /** The current value */
+  current: T
+}
+
+/**
+ * Create a mutable reference container
+ * 
+ * @param initialValue - The initial value (optional, defaults to undefined)
+ * @returns A ref object with a mutable .current property
+ */
+export function zenRef<T>(): Ref<T | undefined>
+export function zenRef<T>(initialValue: T): Ref<T>
+export function zenRef<T>(initialValue?: T): Ref<T | undefined> {
+  return {
+    current: initialValue
+  }
+}
+

package/core/reactivity/zen-signal.ts

@@ -0,0 +1,121 @@
+/**
+ * Zenith Signal - Atomic Reactive Value
+ * 
+ * A signal is the most basic reactive primitive. It holds a single value
+ * and notifies subscribers when the value changes.
+ * 
+ * Features:
+ * - Getter/setter model
+ * - Automatic dependency tracking
+ * - Fine-grained reactivity (no component re-rendering)
+ * 
+ * @example
+ * ```ts
+ * const count = zenSignal(0)
+ * 
+ * // Read value
+ * console.log(count()) // 0
+ * 
+ * // Write value
+ * count(1)
+ * 
+ * // Or use .value
+ * count.value = 2
+ * console.log(count.value) // 2
+ * ```
+ */
+
+import { trackDependency, notifySubscribers, type Subscriber } from './tracking'
+
+/**
+ * Signal interface - callable getter/setter with .value accessor
+ */
+export interface Signal<T> {
+  /** Get the current value (also tracks dependency) */
+  (): T
+  /** Set a new value */
+  (value: T): void
+  /** Get/set value via property */
+  value: T
+  /** Peek at value without tracking */
+  peek(): T
+  /** Subscribe to changes */
+  subscribe(fn: (value: T) => void): () => void
+}
+
+/**
+ * Internal signal state
+ */
+interface SignalState<T> {
+  value: T
+  subscribers: Set<Subscriber>
+}
+
+/**
+ * Create a reactive signal
+ * 
+ * @param initialValue - The initial value of the signal
+ * @returns A signal that can be read and written
+ */
+export function zenSignal<T>(initialValue: T): Signal<T> {
+  const state: SignalState<T> = {
+    value: initialValue,
+    subscribers: new Set()
+  }
+
+  // The signal function - acts as both getter and setter
+  function signal(newValue?: T): T {
+    if (arguments.length === 0) {
+      // Getter - track dependency and return value
+      trackDependency(state.subscribers)
+      return state.value
+    } else {
+      // Setter - update value and notify
+      const oldValue = state.value
+      state.value = newValue as T
+      
+      if (!Object.is(oldValue, newValue)) {
+        notifySubscribers(state.subscribers)
+      }
+      
+      return state.value
+    }
+  }
+
+  // Add .value accessor
+  Object.defineProperty(signal, 'value', {
+    get() {
+      trackDependency(state.subscribers)
+      return state.value
+    },
+    set(newValue: T) {
+      const oldValue = state.value
+      state.value = newValue
+      
+      if (!Object.is(oldValue, newValue)) {
+        notifySubscribers(state.subscribers)
+      }
+    },
+    enumerable: true,
+    configurable: false
+  })
+
+  // Add .peek() - read without tracking
+  ;(signal as Signal<T>).peek = function(): T {
+    return state.value
+  }
+
+  // Add .subscribe() - manual subscription
+  ;(signal as Signal<T>).subscribe = function(fn: (value: T) => void): () => void {
+    const subscriber: Subscriber = () => fn(state.value)
+    state.subscribers.add(subscriber)
+    
+    // Return unsubscribe function
+    return () => {
+      state.subscribers.delete(subscriber)
+    }
+  }
+
+  return signal as Signal<T>
+}
+

package/core/reactivity/zen-state.ts

@@ -0,0 +1,180 @@
+/**
+ * Zenith State - Deep Reactive Object
+ * 
+ * Creates a deeply reactive object using Proxy. Any property access
+ * is tracked, and any mutation triggers effects.
+ * 
+ * Features:
+ * - Deep reactivity via nested Proxies
+ * - Automatic dependency tracking on property access
+ * - Triggers effects on property mutation
+ * 
+ * @example
+ * ```ts
+ * const user = zenState({
+ *   name: 'John',
+ *   address: {
+ *     city: 'NYC'
+ *   }
+ * })
+ * 
+ * // Access triggers tracking
+ * console.log(user.name)
+ * 
+ * // Mutation triggers effects
+ * user.name = 'Jane'
+ * user.address.city = 'LA'
+ * ```
+ */
+
+import { trackDependency, notifySubscribers, type Subscriber } from './tracking'
+
+/**
+ * WeakMap to store proxy targets and their subscriber maps
+ * Key: target object
+ * Value: Map of property key -> subscriber set
+ */
+const proxySubscribers = new WeakMap<object, Map<string | symbol, Set<Subscriber>>>()
+
+/**
+ * WeakMap to store original objects and their proxies
+ * Prevents creating multiple proxies for the same object
+ */
+const proxyCache = new WeakMap<object, object>()
+
+/**
+ * Get or create subscriber set for a property
+ */
+function getPropertySubscribers(target: object, key: string | symbol): Set<Subscriber> {
+  let propertyMap = proxySubscribers.get(target)
+  
+  if (!propertyMap) {
+    propertyMap = new Map()
+    proxySubscribers.set(target, propertyMap)
+  }
+  
+  let subscribers = propertyMap.get(key)
+  
+  if (!subscribers) {
+    subscribers = new Set()
+    propertyMap.set(key, subscribers)
+  }
+  
+  return subscribers
+}
+
+/**
+ * Check if a value should be wrapped in a proxy
+ */
+function shouldProxy(value: unknown): value is object {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+  
+  // Don't proxy special objects
+  if (value instanceof Date || 
+      value instanceof RegExp || 
+      value instanceof Map || 
+      value instanceof Set ||
+      value instanceof WeakMap ||
+      value instanceof WeakSet ||
+      value instanceof Promise ||
+      ArrayBuffer.isView(value)) {
+    return false
+  }
+  
+  return true
+}
+
+/**
+ * Create a reactive proxy for an object
+ */
+function createReactiveProxy<T extends object>(target: T): T {
+  // Check cache first
+  const cached = proxyCache.get(target)
+  if (cached) {
+    return cached as T
+  }
+  
+  const proxy = new Proxy(target, {
+    get(target, key, receiver) {
+      // Track dependency
+      const subscribers = getPropertySubscribers(target, key)
+      trackDependency(subscribers)
+      
+      const value = Reflect.get(target, key, receiver)
+      
+      // Recursively proxy nested objects
+      if (shouldProxy(value)) {
+        return createReactiveProxy(value)
+      }
+      
+      return value
+    },
+    
+    set(target, key, value, receiver) {
+      const oldValue = Reflect.get(target, key, receiver)
+      
+      // Unwrap proxies before storing
+      const rawValue = value
+      
+      const result = Reflect.set(target, key, rawValue, receiver)
+      
+      // Only notify if value actually changed
+      if (!Object.is(oldValue, rawValue)) {
+        const subscribers = getPropertySubscribers(target, key)
+        notifySubscribers(subscribers)
+      }
+      
+      return result
+    },
+    
+    deleteProperty(target, key) {
+      const hadKey = Reflect.has(target, key)
+      const result = Reflect.deleteProperty(target, key)
+      
+      if (hadKey && result) {
+        const subscribers = getPropertySubscribers(target, key)
+        notifySubscribers(subscribers)
+      }
+      
+      return result
+    },
+    
+    has(target, key) {
+      // Track dependency for 'in' operator
+      const subscribers = getPropertySubscribers(target, key)
+      trackDependency(subscribers)
+      
+      return Reflect.has(target, key)
+    },
+    
+    ownKeys(target) {
+      // Track a special 'keys' dependency for iteration
+      const subscribers = getPropertySubscribers(target, Symbol.for('zen:keys'))
+      trackDependency(subscribers)
+      
+      return Reflect.ownKeys(target)
+    }
+  })
+  
+  // Cache the proxy
+  proxyCache.set(target, proxy)
+  
+  return proxy
+}
+
+/**
+ * Create a deeply reactive state object
+ * 
+ * @param initialValue - The initial state object
+ * @returns A reactive proxy of the object
+ */
+export function zenState<T extends object>(initialValue: T): T {
+  if (!shouldProxy(initialValue)) {
+    throw new Error('zenState requires a plain object or array')
+  }
+  
+  return createReactiveProxy(initialValue)
+}
+

package/core/reactivity/zen-untrack.ts

@@ -0,0 +1,44 @@
+/**
+ * Zenith Untrack - Escape Dependency Tracking
+ * 
+ * Allows reading reactive values without creating a dependency.
+ * Useful when you need to read a value inside an effect but don't
+ * want the effect to re-run when that value changes.
+ * 
+ * Features:
+ * - Disables dependency tracking within the callback
+ * - Returns the callback's return value
+ * - Can be nested
+ * 
+ * @example
+ * ```ts
+ * const count = zenSignal(0)
+ * const multiplier = zenSignal(2)
+ * 
+ * zenEffect(() => {
+ *   // This creates a dependency on 'count'
+ *   const c = count()
+ *   
+ *   // This does NOT create a dependency on 'multiplier'
+ *   const m = zenUntrack(() => multiplier())
+ *   
+ *   console.log(c * m)
+ * })
+ * 
+ * count(5)       // Effect re-runs
+ * multiplier(3)  // Effect does NOT re-run
+ * ```
+ */
+
+import { runUntracked } from './tracking'
+
+/**
+ * Execute a function without tracking dependencies
+ * 
+ * @param fn - The function to execute
+ * @returns The return value of the function
+ */
+export function zenUntrack<T>(fn: () => T): T {
+  return runUntracked(fn)
+}
+

package/docs/COMMENTS.md

@@ -0,0 +1,111 @@
+# Conventional Comments
+
+Zenith uses [Conventional Comments](https://conventionalcomments.org/) to provide clear, actionable feedback in pull requests.
+
+## Format
+
+```
+<label> [decorations]: <subject>
+
+[discussion]
+```
+
+## 💫 Quick Reference
+### Labels
+
+| Label        | Description                                          | Example Use Case                           |
+|--------------|------------------------------------------------------|-------------------------------------------|
+| **praise**   | Highlight something positive                         | Great implementation, well-documented code |
+| **nitpick**  | Minor suggestions that don't require changes         | Variable naming, minor style preferences   |
+| **suggestion** | Propose improvements to consider                   | Alternative approaches, optimizations      |
+| **issue**    | Highlight problems that need to be resolved          | Bugs, errors, critical problems            |
+| **question** | Ask for clarification or explanation                 | Understanding intent, approach questions   |
+| **thought**  | Share ideas or considerations for the future         | Architectural thoughts, future improvements |
+| **chore**    | Simple tasks like formatting or typos                | Missing semicolons, typos, formatting      |
+
+### Decorations
+
+| Decoration        | Meaning                                              |
+|-------------------|------------------------------------------------------|
+| **(non-blocking)** | Optional feedback - PR can merge without addressing |
+| **(blocking)**    | Must be addressed before merge                       |
+| **(if-minor)**    | Address only if it's a quick fix                     |
+
+## Examples
+
+### Praise
+```
+praise: Excellent error handling here!
+
+This covers all the edge cases I was worried about.
+```
+
+### Nitpick (non-blocking)
+```
+nitpick (non-blocking): Consider renaming `temp` to `processedData`
+
+While `temp` works, a more descriptive name might help future maintainers.
+```
+
+### Suggestion
+```
+suggestion: We could use a Map instead of an Object here for better performance
+
+Since we're doing frequent lookups, a Map would give us O(1) access time
+and better memory characteristics for this use case.
+```
+
+### Issue (blocking)
+```
+issue (blocking): This will throw when `items` is undefined
+
+We need to add a null/undefined check before calling `.map()` on line 42.
+```
+
+### Question
+```
+question: Why are we processing this data twice?
+
+I see similar logic on lines 15 and 78. Is there a reason we can't
+consolidate these operations?
+```
+
+### Thought
+```
+thought: This might be a good candidate for a custom hook in the future
+
+Not for this PR, but as we add more components with similar behavior,
+extracting this pattern could be valuable.
+```
+
+### Chore
+```
+chore (if-minor): Missing semicolon on line 23
+```
+
+## Best Practices
+
+1. **Be specific** - Reference line numbers or code sections
+2. **Be kind** - Remember there's a human on the other side
+3. **Be clear** - Explain the "why" behind your feedback
+4. **Use blocking sparingly** - Only for issues that truly need resolution
+5. **Praise good work** - Positive feedback is valuable!
+
+## Quick Tips for Reviewers
+
+- Start with **praise** for good work
+- Use **suggestion** for most feedback (not blocking unless critical)
+- Reserve **issue (blocking)** for bugs or critical problems
+- Use **question** when you don't understand something
+- Mark style preferences as **nitpick (non-blocking)**
+
+## Quick Tips for Authors
+
+- Don't take **nitpicks** personally - they're optional
+- Ask for clarification on unclear **questions** or **suggestions**
+- Address all **blocking** comments before requesting re-review
+- Thank reviewers for their time and feedback
+
+---
+
+**Remember**: The goal is constructive collaboration, not perfection. Use these conventions to make reviews clearer and more productive for everyone.

package/docs/COMMITS.md

@@ -0,0 +1,36 @@
+## TL;DR
+***If you find that this is tanking your productivity just use `feat` or `fix` and always apply `!` if pushing breaking changes***
+
+## Why bother with conventional commits?
+- _The most important reason for us is to simplify/automate SemVer and our Release strategy_
+- For this reason, please prefix all commits with one of the below [Prefixes](#prefixes)
+
+## How does this relate to SemVer?
+- `fix` type commits should be translated to `PATCH` releases.
+- `feat` type commits should be translated to `MINOR` releases.
+- Commits with `BREAKING CHANGE` or `!` (e.g. `feat!: extend parser`) in the commits, regardless of type, should be translated to `MAJOR` releases.
+
+## Prefixes
+| Commit Prefix   | SemVer Equivalent | Example                              |
+| --------------- | ----------------- | ------------------------------------ |
+| fix:            | PATCH - 0.0.n     | fix: html not recognizing state      |
+| feat:           | MINOR - 0.n.0     | feat: phase 2 event loop             |
+| fix!:           | MAJOR - n.0.0     | fix!: html not recognizing state     |
+| feat!:          | MAJOR - n.0.0     | feat!: phase 2 event loop            |
+| BREAKING CHANGE | MAJOR - n.0.0     | fix: BREAKING CHANGE component state |
+| BREAKING-CHANGE | MAJOR - n.0.0     | feat: BREAKING-CHANGE build phase 2  |
+| docs:           | CHANGELOG         | ...                                  |
+| chore:          | CHANGELOG         | ...                                  |
+| style:          | CHANGELOG         | ...                                  |
+| test:           | CHANGELOG         | ...                                  |
+| refactor:       | CHANGELOG         | ...                                  |
+
+### Glossary
+
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `docs:` - Documentation changes
+- `style:` - Code style changes (formatting, no logic change)
+- `refactor:` - Code refactoring
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks