@zenithbuild/compiler 1.0.2

package/dist/core/plugins/registry.js

@@ -0,0 +1,113 @@
+/**
+ * Zenith Plugin Registry
+ *
+ * Manages plugin registration and initialization
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOOK OWNERSHIP RULE (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * The plugin registry is part of core infrastructure.
+ * It MUST remain plugin-agnostic:
+ *   - No plugin-specific types
+ *   - No plugin-specific logic
+ *   - Generic data handling only
+ *
+ * Plugins own their data structures; core provides the storage mechanism.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+/**
+ * Global plugin data store
+ *
+ * Plugins store their data here using namespaced keys.
+ * Core does not interpret this data - it just stores and serves it.
+ */
+const pluginDataStore = {};
+/**
+ * Get all plugin data (for runtime access)
+ */
+export function getPluginData() {
+    return { ...pluginDataStore };
+}
+/**
+ * Get plugin data by namespace
+ */
+export function getPluginDataByNamespace(namespace) {
+    return pluginDataStore[namespace] || [];
+}
+/**
+ * Plugin registry for managing Zenith plugins
+ */
+export class PluginRegistry {
+    plugins = new Map();
+    /**
+     * Register a plugin
+     */
+    register(plugin) {
+        if (this.plugins.has(plugin.name)) {
+            console.warn(`[Zenith] Plugin "${plugin.name}" is already registered. Overwriting.`);
+        }
+        this.plugins.set(plugin.name, plugin);
+    }
+    /**
+     * Get a plugin by name
+     */
+    get(name) {
+        return this.plugins.get(name);
+    }
+    /**
+     * Check if a plugin is registered
+     */
+    has(name) {
+        return this.plugins.has(name);
+    }
+    /**
+     * Get all registered plugins
+     */
+    all() {
+        return Array.from(this.plugins.values());
+    }
+    /**
+     * Initialize all plugins with the provided context
+     */
+    async initAll(ctx) {
+        for (const plugin of this.plugins.values()) {
+            try {
+                await plugin.setup(ctx);
+                console.log(`[Zenith] Plugin "${plugin.name}" initialized`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`[Zenith] Failed to initialize plugin "${plugin.name}":`, message);
+            }
+        }
+    }
+    /**
+     * Clear all registered plugins
+     */
+    clear() {
+        this.plugins.clear();
+        // Also clear plugin data
+        for (const key of Object.keys(pluginDataStore)) {
+            delete pluginDataStore[key];
+        }
+    }
+}
+/**
+ * Create a plugin context for initialization
+ *
+ * Uses a generic data setter that stores data by namespace.
+ * Plugins define their own data structures internally.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns A PluginContext for plugin initialization
+ */
+export function createPluginContext(projectRoot) {
+    return {
+        projectRoot,
+        setPluginData: (namespace, data) => {
+            pluginDataStore[namespace] = data;
+        },
+        options: {}
+    };
+}

package/dist/core/reactivity/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Zenith Reactivity System
+ *
+ * This module exports all reactive primitives for the Zenith framework.
+ *
+ * Exports both explicit `zen*` names (internal) and clean aliases (public DX).
+ */
+import { zenSignal as _zenSignal, type Signal } from './zen-signal';
+import { zenState as _zenState } from './zen-state';
+import { zenEffect as _zenEffect, type EffectFn, type DisposeFn } from './zen-effect';
+import { zenMemo as _zenMemo, type Memo } from './zen-memo';
+import { zenRef as _zenRef, type Ref } from './zen-ref';
+import { zenBatch as _zenBatch } from './zen-batch';
+import { zenUntrack as _zenUntrack } from './zen-untrack';
+export declare const zenSignal: typeof _zenSignal;
+export declare const zenState: typeof _zenState;
+export declare const zenEffect: typeof _zenEffect;
+export declare const zenMemo: typeof _zenMemo;
+export declare const zenRef: typeof _zenRef;
+export declare const zenBatch: typeof _zenBatch;
+export declare const zenUntrack: typeof _zenUntrack;
+export type { Signal, Memo, Ref, EffectFn, DisposeFn };
+export { type Subscriber, type TrackingContext, trackDependency, notifySubscribers, getCurrentContext, pushContext, popContext, cleanupContext, runUntracked, startBatch, endBatch, isBatching } from './tracking';
+export declare const signal: typeof _zenSignal;
+export declare const state: typeof _zenState;
+export declare const effect: typeof _zenEffect;
+export declare const memo: typeof _zenMemo;
+export declare const ref: typeof _zenRef;
+export declare const batch: typeof _zenBatch;
+export declare const untrack: typeof _zenUntrack;

package/dist/core/reactivity/index.js

@@ -0,0 +1,33 @@
+/**
+ * Zenith Reactivity System
+ *
+ * This module exports all reactive primitives for the Zenith framework.
+ *
+ * Exports both explicit `zen*` names (internal) and clean aliases (public DX).
+ */
+// Core primitives - explicit names
+import { zenSignal as _zenSignal } from './zen-signal';
+import { zenState as _zenState } from './zen-state';
+import { zenEffect as _zenEffect } from './zen-effect';
+import { zenMemo as _zenMemo } from './zen-memo';
+import { zenRef as _zenRef } from './zen-ref';
+import { zenBatch as _zenBatch } from './zen-batch';
+import { zenUntrack as _zenUntrack } from './zen-untrack';
+// Re-export with explicit names
+export const zenSignal = _zenSignal;
+export const zenState = _zenState;
+export const zenEffect = _zenEffect;
+export const zenMemo = _zenMemo;
+export const zenRef = _zenRef;
+export const zenBatch = _zenBatch;
+export const zenUntrack = _zenUntrack;
+// Internal tracking utilities (for advanced use)
+export { trackDependency, notifySubscribers, getCurrentContext, pushContext, popContext, cleanupContext, runUntracked, startBatch, endBatch, isBatching } from './tracking';
+// Public DX aliases - clean names
+export const signal = _zenSignal;
+export const state = _zenState;
+export const effect = _zenEffect;
+export const memo = _zenMemo;
+export const ref = _zenRef;
+export const batch = _zenBatch;
+export const untrack = _zenUntrack;

package/dist/core/reactivity/tracking.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Zenith Reactivity Tracking System
+ *
+ * This module provides the core dependency tracking mechanism used by
+ * signals, effects, and memos. It uses a stack-based approach to track
+ * which reactive values are accessed during effect/memo execution.
+ *
+ * Key concepts:
+ * - Subscriber: A function that should be called when a dependency changes
+ * - Tracking context: The currently executing effect/memo that should collect dependencies
+ * - Dependency: A reactive value that an effect/memo depends on
+ */
+/**
+ * A subscriber is a function that gets called when a reactive value changes
+ */
+export type Subscriber = () => void;
+/**
+ * Tracking context - represents an effect or memo that is collecting dependencies
+ */
+export interface TrackingContext {
+    /** The function to call when dependencies change */
+    execute: Subscriber;
+    /** Set of dependency subscriber sets this context is registered with */
+    dependencies: Set<Set<Subscriber>>;
+}
+/**
+ * Get the current tracking context (if any)
+ */
+export declare function getCurrentContext(): TrackingContext | undefined;
+/**
+ * Push a new tracking context onto the stack
+ */
+export declare function pushContext(context: TrackingContext): void;
+/**
+ * Pop the current tracking context from the stack
+ */
+export declare function popContext(): TrackingContext | undefined;
+/**
+ * Track a dependency - called when a reactive value is read
+ *
+ * @param subscribers - The subscriber set of the reactive value being read
+ */
+export declare function trackDependency(subscribers: Set<Subscriber>): void;
+/**
+ * Notify subscribers that a reactive value has changed
+ *
+ * @param subscribers - The subscriber set to notify
+ */
+export declare function notifySubscribers(subscribers: Set<Subscriber>): void;
+/**
+ * Clean up a tracking context - remove it from all dependency sets
+ *
+ * @param context - The context to clean up
+ */
+export declare function cleanupContext(context: TrackingContext): void;
+/**
+ * Run a function without tracking dependencies
+ *
+ * @param fn - The function to run
+ * @returns The return value of the function
+ */
+export declare function runUntracked<T>(fn: () => T): T;
+/**
+ * Start a batch - defer effect execution until batch ends
+ */
+export declare function startBatch(): void;
+/**
+ * End a batch - run all pending effects
+ */
+export declare function endBatch(): void;
+/**
+ * Check if currently inside a batch
+ */
+export declare function isBatching(): boolean;

package/dist/core/reactivity/tracking.js

@@ -0,0 +1,136 @@
+/**
+ * Zenith Reactivity Tracking System
+ *
+ * This module provides the core dependency tracking mechanism used by
+ * signals, effects, and memos. It uses a stack-based approach to track
+ * which reactive values are accessed during effect/memo execution.
+ *
+ * Key concepts:
+ * - Subscriber: A function that should be called when a dependency changes
+ * - Tracking context: The currently executing effect/memo that should collect dependencies
+ * - Dependency: A reactive value that an effect/memo depends on
+ */
+/**
+ * Stack of currently executing tracking contexts
+ * When an effect runs, it pushes itself onto this stack.
+ * When a signal is read, it registers the top of the stack as a subscriber.
+ */
+const trackingStack = [];
+/**
+ * Flag to disable tracking (used by zenUntrack)
+ */
+let trackingDisabled = false;
+/**
+ * Batch depth counter - when > 0, effect execution is deferred
+ */
+let batchDepth = 0;
+/**
+ * Queue of effects to run after batch completes
+ */
+const pendingEffects = new Set();
+/**
+ * Get the current tracking context (if any)
+ */
+export function getCurrentContext() {
+    if (trackingDisabled)
+        return undefined;
+    return trackingStack[trackingStack.length - 1];
+}
+/**
+ * Push a new tracking context onto the stack
+ */
+export function pushContext(context) {
+    trackingStack.push(context);
+}
+/**
+ * Pop the current tracking context from the stack
+ */
+export function popContext() {
+    return trackingStack.pop();
+}
+/**
+ * Track a dependency - called when a reactive value is read
+ *
+ * @param subscribers - The subscriber set of the reactive value being read
+ */
+export function trackDependency(subscribers) {
+    const context = getCurrentContext();
+    if (context) {
+        // Register this effect as a subscriber to the signal
+        subscribers.add(context.execute);
+        // Track that this effect depends on this signal
+        context.dependencies.add(subscribers);
+    }
+}
+/**
+ * Notify subscribers that a reactive value has changed
+ *
+ * @param subscribers - The subscriber set to notify
+ */
+export function notifySubscribers(subscribers) {
+    // Copy subscribers to avoid issues if the set is modified during iteration
+    const toNotify = [...subscribers];
+    for (const subscriber of toNotify) {
+        if (batchDepth > 0) {
+            // Batching - defer effect execution
+            pendingEffects.add(subscriber);
+        }
+        else {
+            // Execute immediately
+            subscriber();
+        }
+    }
+}
+/**
+ * Clean up a tracking context - remove it from all dependency sets
+ *
+ * @param context - The context to clean up
+ */
+export function cleanupContext(context) {
+    for (const deps of context.dependencies) {
+        deps.delete(context.execute);
+    }
+    context.dependencies.clear();
+}
+/**
+ * Run a function without tracking dependencies
+ *
+ * @param fn - The function to run
+ * @returns The return value of the function
+ */
+export function runUntracked(fn) {
+    const wasDisabled = trackingDisabled;
+    trackingDisabled = true;
+    try {
+        return fn();
+    }
+    finally {
+        trackingDisabled = wasDisabled;
+    }
+}
+/**
+ * Start a batch - defer effect execution until batch ends
+ */
+export function startBatch() {
+    batchDepth++;
+}
+/**
+ * End a batch - run all pending effects
+ */
+export function endBatch() {
+    batchDepth--;
+    if (batchDepth === 0 && pendingEffects.size > 0) {
+        // Run all pending effects
+        const effects = [...pendingEffects];
+        pendingEffects.clear();
+        for (const effect of effects) {
+            effect();
+        }
+    }
+}
+/**
+ * Check if currently inside a batch
+ */
+export function isBatching() {
+    return batchDepth > 0;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Zenith Batch - Deferred Effect Execution
+ *
+ * Batching allows you to make multiple reactive updates without
+ * triggering effects until all updates are complete. This improves
+ * performance by preventing redundant effect executions.
+ *
+ * Features:
+ * - Groups multiple mutations
+ * - Defers effect execution until batch completes
+ * - Supports nested batches
+ * - Automatically flushes on completion
+ *
+ * @example
+ * ```ts
+ * const firstName = zenSignal('John')
+ * const lastName = zenSignal('Doe')
+ *
+ * zenEffect(() => {
+ *   console.log(`${firstName()} ${lastName()}`)
+ * })
+ * // Logs: "John Doe"
+ *
+ * // Without batch - effect runs twice
+ * firstName('Jane')  // Logs: "Jane Doe"
+ * lastName('Smith')  // Logs: "Jane Smith"
+ *
+ * // With batch - effect runs once
+ * zenBatch(() => {
+ *   firstName('Bob')
+ *   lastName('Brown')
+ * })
+ * // Logs: "Bob Brown" (only once)
+ * ```
+ */
+/**
+ * Execute a function with batched updates
+ *
+ * All reactive updates inside the batch will be collected,
+ * and effects will only run once after the batch completes.
+ *
+ * @param fn - The function to execute
+ * @returns The return value of the function
+ */
+export declare function zenBatch<T>(fn: () => T): T;

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

@@ -0,0 +1,54 @@
+/**
+ * Zenith Batch - Deferred Effect Execution
+ *
+ * Batching allows you to make multiple reactive updates without
+ * triggering effects until all updates are complete. This improves
+ * performance by preventing redundant effect executions.
+ *
+ * Features:
+ * - Groups multiple mutations
+ * - Defers effect execution until batch completes
+ * - Supports nested batches
+ * - Automatically flushes on completion
+ *
+ * @example
+ * ```ts
+ * const firstName = zenSignal('John')
+ * const lastName = zenSignal('Doe')
+ *
+ * zenEffect(() => {
+ *   console.log(`${firstName()} ${lastName()}`)
+ * })
+ * // Logs: "John Doe"
+ *
+ * // Without batch - effect runs twice
+ * firstName('Jane')  // Logs: "Jane Doe"
+ * lastName('Smith')  // Logs: "Jane Smith"
+ *
+ * // With batch - effect runs once
+ * zenBatch(() => {
+ *   firstName('Bob')
+ *   lastName('Brown')
+ * })
+ * // Logs: "Bob Brown" (only once)
+ * ```
+ */
+import { startBatch, endBatch } from './tracking';
+/**
+ * Execute a function with batched updates
+ *
+ * All reactive updates inside the batch will be collected,
+ * and effects will only run once after the batch completes.
+ *
+ * @param fn - The function to execute
+ * @returns The return value of the function
+ */
+export function zenBatch(fn) {
+    startBatch();
+    try {
+        return fn();
+    }
+    finally {
+        endBatch();
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Zenith Effect - Auto-Tracked Side Effect
+ *
+ * Effects are functions that automatically track their reactive dependencies
+ * and re-run when those dependencies change. They are the bridge between
+ * reactive state and side effects (DOM updates, logging, API calls, etc.)
+ *
+ * Features:
+ * - Automatic dependency tracking (no dependency arrays)
+ * - Runs immediately on creation
+ * - Re-runs when dependencies change
+ * - Supports cleanup functions
+ * - Can be manually disposed
+ *
+ * @example
+ * ```ts
+ * const count = zenSignal(0)
+ *
+ * // Effect runs immediately, then re-runs when count changes
+ * const dispose = zenEffect(() => {
+ *   console.log('Count:', count())
+ *
+ *   // Optional cleanup - runs before next execution or on dispose
+ *   return () => {
+ *     console.log('Cleanup')
+ *   }
+ * })
+ *
+ * count(1) // Logs: "Cleanup", then "Count: 1"
+ *
+ * dispose() // Cleanup and stop watching
+ * ```
+ */
+/**
+ * Effect function type - can optionally return a cleanup function
+ */
+export type EffectFn = () => void | (() => void);
+/**
+ * Dispose function - call to stop the effect
+ */
+export type DisposeFn = () => void;
+/**
+ * Create an auto-tracked side effect
+ *
+ * @param fn - The effect function to run
+ * @returns A dispose function to stop the effect
+ */
+export declare function zenEffect(fn: EffectFn): DisposeFn;

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

@@ -0,0 +1,98 @@
+/**
+ * Zenith Effect - Auto-Tracked Side Effect
+ *
+ * Effects are functions that automatically track their reactive dependencies
+ * and re-run when those dependencies change. They are the bridge between
+ * reactive state and side effects (DOM updates, logging, API calls, etc.)
+ *
+ * Features:
+ * - Automatic dependency tracking (no dependency arrays)
+ * - Runs immediately on creation
+ * - Re-runs when dependencies change
+ * - Supports cleanup functions
+ * - Can be manually disposed
+ *
+ * @example
+ * ```ts
+ * const count = zenSignal(0)
+ *
+ * // Effect runs immediately, then re-runs when count changes
+ * const dispose = zenEffect(() => {
+ *   console.log('Count:', count())
+ *
+ *   // Optional cleanup - runs before next execution or on dispose
+ *   return () => {
+ *     console.log('Cleanup')
+ *   }
+ * })
+ *
+ * count(1) // Logs: "Cleanup", then "Count: 1"
+ *
+ * dispose() // Cleanup and stop watching
+ * ```
+ */
+import { pushContext, popContext, cleanupContext } from './tracking';
+/**
+ * Create an auto-tracked side effect
+ *
+ * @param fn - The effect function to run
+ * @returns A dispose function to stop the effect
+ */
+export function zenEffect(fn) {
+    const state = {
+        fn,
+        cleanup: null,
+        context: {
+            execute: () => runEffect(state),
+            dependencies: new Set()
+        },
+        disposed: false
+    };
+    // Run the effect immediately
+    runEffect(state);
+    // Return dispose function
+    return () => disposeEffect(state);
+}
+/**
+ * Run an effect, tracking dependencies
+ */
+function runEffect(state) {
+    if (state.disposed)
+        return;
+    // Run cleanup from previous execution
+    if (state.cleanup) {
+        state.cleanup();
+        state.cleanup = null;
+    }
+    // Clean up old dependencies
+    cleanupContext(state.context);
+    // Push this effect onto the tracking stack
+    pushContext(state.context);
+    try {
+        // Run the effect function
+        const result = state.fn();
+        // Store cleanup if returned
+        if (typeof result === 'function') {
+            state.cleanup = result;
+        }
+    }
+    finally {
+        // Pop from tracking stack
+        popContext();
+    }
+}
+/**
+ * Dispose an effect - run cleanup and stop watching
+ */
+function disposeEffect(state) {
+    if (state.disposed)
+        return;
+    state.disposed = true;
+    // Run cleanup
+    if (state.cleanup) {
+        state.cleanup();
+        state.cleanup = null;
+    }
+    // Remove from all dependency sets
+    cleanupContext(state.context);
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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)
+ * ```
+ */
+/**
+ * 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;
+}
+/**
+ * Create a memoized computed value
+ *
+ * @param fn - The computation function
+ * @returns A memo that can be read to get the computed value
+ */
+export declare function zenMemo<T>(fn: () => T): Memo<T>;