@zenithbuild/compiler 1.0.2

package/dist/core/reactivity/zen-memo.js

@@ -0,0 +1,100 @@
+/**
+ * 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 } from './tracking';
+/**
+ * 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(fn) {
+    const state = {
+        fn,
+        value: undefined,
+        dirty: true,
+        context: {
+            execute: () => markDirty(state),
+            dependencies: new Set()
+        },
+        subscribers: new Set(),
+        initialized: false
+    };
+    function memo() {
+        // Track that something is reading this memo
+        trackDependency(state.subscribers);
+        // Recompute if dirty
+        if (state.dirty) {
+            computeMemo(state);
+        }
+        return state.value;
+    }
+    // Add peek method
+    ;
+    memo.peek = function () {
+        // Return cached value without tracking or recomputing
+        if (state.dirty && !state.initialized) {
+            computeMemo(state);
+        }
+        return state.value;
+    };
+    return memo;
+}
+/**
+ * Compute the memo value, tracking dependencies
+ */
+function computeMemo(state) {
+    // 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(state) {
+    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/dist/core/reactivity/zen-ref.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare function zenRef<T>(): Ref<T | undefined>;
+export declare function zenRef<T>(initialValue: T): Ref<T>;

package/dist/core/reactivity/zen-ref.js

@@ -0,0 +1,34 @@
+/**
+ * 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
+ * ```
+ */
+export function zenRef(initialValue) {
+    return {
+        current: initialValue
+    };
+}

package/dist/core/reactivity/zen-signal.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ * ```
+ */
+/**
+ * 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;
+}
+/**
+ * Create a reactive signal
+ *
+ * @param initialValue - The initial value of the signal
+ * @returns A signal that can be read and written
+ */
+export declare function zenSignal<T>(initialValue: T): Signal<T>;

package/dist/core/reactivity/zen-signal.js

@@ -0,0 +1,84 @@
+/**
+ * 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 } from './tracking';
+/**
+ * Create a reactive signal
+ *
+ * @param initialValue - The initial value of the signal
+ * @returns A signal that can be read and written
+ */
+export function zenSignal(initialValue) {
+    const state = {
+        value: initialValue,
+        subscribers: new Set()
+    };
+    // The signal function - acts as both getter and setter
+    function signal(newValue) {
+        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;
+            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) {
+            const oldValue = state.value;
+            state.value = newValue;
+            if (!Object.is(oldValue, newValue)) {
+                notifySubscribers(state.subscribers);
+            }
+        },
+        enumerable: true,
+        configurable: false
+    });
+    signal.peek = function () {
+        return state.value;
+    };
+    signal.subscribe = function (fn) {
+        const subscriber = () => fn(state.value);
+        state.subscribers.add(subscriber);
+        // Return unsubscribe function
+        return () => {
+            state.subscribers.delete(subscriber);
+        };
+    };
+    return signal;
+}

package/dist/core/reactivity/zen-state.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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'
+ * ```
+ */
+/**
+ * Create a deeply reactive state object
+ *
+ * @param initialValue - The initial state object
+ * @returns A reactive proxy of the object
+ */
+export declare function zenState<T extends object>(initialValue: T): T;

package/dist/core/reactivity/zen-state.js

@@ -0,0 +1,147 @@
+/**
+ * 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 } 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();
+/**
+ * WeakMap to store original objects and their proxies
+ * Prevents creating multiple proxies for the same object
+ */
+const proxyCache = new WeakMap();
+/**
+ * Get or create subscriber set for a property
+ */
+function getPropertySubscribers(target, key) {
+    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) {
+    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(target) {
+    // Check cache first
+    const cached = proxyCache.get(target);
+    if (cached) {
+        return cached;
+    }
+    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(initialValue) {
+    if (!shouldProxy(initialValue)) {
+        throw new Error('zenState requires a plain object or array');
+    }
+    return createReactiveProxy(initialValue);
+}

package/dist/core/reactivity/zen-untrack.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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
+ * ```
+ */
+/**
+ * Execute a function without tracking dependencies
+ *
+ * @param fn - The function to execute
+ * @returns The return value of the function
+ */
+export declare function zenUntrack<T>(fn: () => T): T;

package/dist/core/reactivity/zen-untrack.js

@@ -0,0 +1,41 @@
+/**
+ * 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(fn) {
+    return runUntracked(fn);
+}

package/dist/css/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Zenith CSS Compiler Module
+ *
+ * Compiler-owned CSS processing that integrates Tailwind CSS v4 JIT
+ * at compile time. This module ensures:
+ *
+ * 1. All CSS is processed at build time (no runtime generation)
+ * 2. Tailwind sees all .zen templates for class scanning
+ * 3. HMR support for instant CSS updates in dev mode
+ * 4. Deterministic, cacheable output for production
+ *
+ * Per Zenith CSS Directive: The compiler owns styles.
+ */
+export interface CSSCompileOptions {
+    /** Input CSS file path (e.g., src/styles/globals.css) */
+    input: string;
+    /** Output CSS file path, or ':memory:' for in-memory result */
+    output: string;
+    /** Enable minification for production */
+    minify?: boolean;
+    /** Watch mode for HMR */
+    watch?: boolean;
+}
+export interface CSSCompileResult {
+    /** Compiled CSS content */
+    css: string;
+    /** Compilation time in milliseconds */
+    duration: number;
+    /** Whether compilation succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Compile CSS using Tailwind CSS v4 CLI
+ *
+ * This function synchronously compiles CSS for use in:
+ * - Dev server startup
+ * - SSG build
+ * - On-demand recompilation
+ *
+ * @param options Compilation options
+ * @returns Compiled CSS result
+ */
+export declare function compileCss(options: CSSCompileOptions): CSSCompileResult;
+/**
+ * Compile CSS asynchronously (non-blocking)
+ *
+ * Used for HMR updates where we don't want to block the main thread.
+ */
+export declare function compileCssAsync(options: CSSCompileOptions): Promise<CSSCompileResult>;
+export interface CSSWatchOptions extends CSSCompileOptions {
+    /** Callback when CSS changes */
+    onChange: (result: CSSCompileResult) => void;
+    /** Debounce delay in ms */
+    debounce?: number;
+}
+/**
+ * Watch CSS and source files for changes, recompile on change
+ *
+ * This is used by the dev server for HMR support.
+ * It watches both the CSS entry point AND all .zen files
+ * that Tailwind scans for class names.
+ */
+export declare function watchCss(options: CSSWatchOptions): () => void;
+/**
+ * Resolve the canonical globals.css path for a Zenith project
+ */
+export declare function resolveGlobalsCss(projectRoot: string): string | null;
+/**
+ * Get the output path for compiled CSS
+ */
+export declare function getCompiledCssPath(projectRoot: string, mode: 'dev' | 'build'): string;