@zenithbuild/runtime 0.6.5 → 0.6.7

package/dist/cleanup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Register an effect disposer for later cleanup.
+ *
+ * @param {function} dispose
+ */
+export function _registerDisposer(dispose: Function): void;
+/**
+ * Register an event listener for later cleanup.
+ *
+ * @param {Element} element
+ * @param {string} event
+ * @param {function} handler
+ */
+export function _registerListener(element: Element, event: string, handler: Function): void;
+/**
+ * Tear down all active effects and event listeners.
+ *
+ * - Disposes all effects (clears subscriber sets)
+ * - Removes all event listeners
+ * - Clears registries
+ * - Idempotent: calling twice is a no-op
+ */
+export function cleanup(): void;
+/**
+ * Get counts for testing/debugging.
+ * @returns {{ effects: number, listeners: number }}
+ */
+export function _getCounts(): {
+    effects: number;
+    listeners: number;
+};

package/dist/cleanup.js

@@ -10,17 +10,12 @@
 // cleanup() removes everything.
 // Calling cleanup() twice is a no-op.
 // ---------------------------------------------------------------------------
-
 import { resetGlobalSideEffects } from './zeneffect.js';
-
 /** @type {function[]} */
 const _disposers = [];
-
 /** @type {{ element: Element, event: string, handler: function }[]} */
 const _listeners = [];
-
 let _cleaned = false;
-
 /**
  * Register an effect disposer for later cleanup.
  *
@@ -30,7 +25,6 @@ export function _registerDisposer(dispose) {
     _disposers.push(dispose);
     _cleaned = false;
 }
-
 /**
  * Register an event listener for later cleanup.
  *
@@ -42,7 +36,6 @@ export function _registerListener(element, event, handler) {
     _listeners.push({ element, event, handler });
     _cleaned = false;
 }
-
 /**
  * Tear down all active effects and event listeners.
  *
@@ -59,23 +52,19 @@ export function cleanup() {
         resetGlobalSideEffects();
         return;
     }
-
     // 1. Dispose all effects
     for (let i = 0; i < _disposers.length; i++) {
         _disposers[i]();
     }
     _disposers.length = 0;
-
     // 2. Remove all event listeners
     for (let i = 0; i < _listeners.length; i++) {
         const { element, event, handler } = _listeners[i];
         element.removeEventListener(event, handler);
     }
     _listeners.length = 0;
-
     _cleaned = true;
 }
-
 /**
  * Get counts for testing/debugging.
  * @returns {{ effects: number, listeners: number }}

package/dist/diagnostics.d.ts

@@ -0,0 +1,4 @@
+export function isZenithRuntimeError(error: any): boolean;
+export function createZenithRuntimeError(details: any, cause: any): Error;
+export function throwZenithRuntimeError(details: any, cause: any): void;
+export function rethrowZenithRuntimeError(error: any, fallback?: {}): void;

package/dist/diagnostics.js

@@ -2,7 +2,6 @@ const OVERLAY_ID = '__zenith_runtime_error_overlay';
 const MAX_MESSAGE_LENGTH = 120;
 const MAX_HINT_LENGTH = 140;
 const MAX_PATH_LENGTH = 120;
-
 const VALID_PHASES = new Set(['hydrate', 'bind', 'render', 'event']);
 const VALID_CODES = new Set([
     'UNRESOLVED_EXPRESSION',
@@ -12,13 +11,12 @@ const VALID_CODES = new Set([
     'BINDING_APPLY_FAILED',
     'EVENT_HANDLER_FAILED'
 ]);
-
 function _truncate(input, maxLength) {
     const text = String(input ?? '');
-    if (text.length <= maxLength) return text;
+    if (text.length <= maxLength)
+        return text;
     return `${text.slice(0, maxLength - 3)}...`;
 }
-
 function _sanitizeAbsolutePaths(value) {
     return String(value ?? '')
         .replace(/[A-Za-z]:\\[^\s"'`]+/g, '<path>')
@@ -28,57 +26,78 @@ function _sanitizeAbsolutePaths(value) {
         .replace(/\/tmp\/[^\s"'`]+/g, '<path>')
         .replace(/\/var\/folders\/[^\s"'`]+/g, '<path>');
 }
-
 function _sanitizeMessage(value) {
     const compact = _sanitizeAbsolutePaths(value).replace(/\s+/g, ' ').trim();
     return _truncate(compact || 'Runtime failure', MAX_MESSAGE_LENGTH);
 }
-
 function _sanitizeHint(value) {
     if (value === null || value === undefined || value === false) {
         return undefined;
     }
     const compact = _sanitizeAbsolutePaths(value).replace(/\s+/g, ' ').trim();
-    if (!compact) return undefined;
+    if (!compact)
+        return undefined;
     return _truncate(compact, MAX_HINT_LENGTH);
 }
-
 function _sanitizePath(value) {
     if (value === null || value === undefined || value === false) {
         return undefined;
     }
     const compact = _sanitizeAbsolutePaths(value).replace(/\s+/g, ' ').trim();
-    if (!compact) return undefined;
+    if (!compact)
+        return undefined;
     return _truncate(compact, MAX_PATH_LENGTH);
 }
-
 function _normalizeMarker(marker) {
-    if (!marker || typeof marker !== 'object') return undefined;
+    if (!marker || typeof marker !== 'object')
+        return undefined;
     const markerType = _truncate(_sanitizeAbsolutePaths(marker.type || 'data-zx'), 48);
     const markerId = marker.id;
-    if (markerId === null || markerId === undefined || markerId === '') return undefined;
+    if (markerId === null || markerId === undefined || markerId === '')
+        return undefined;
     if (typeof markerId === 'number') {
         return { type: markerType, id: markerId };
     }
     return { type: markerType, id: _truncate(_sanitizeAbsolutePaths(markerId), 48) };
 }
-
 function _extractErrorMessage(error) {
-    if (!error) return '';
-    if (typeof error === 'string') return error;
-    if (error instanceof Error && typeof error.message === 'string') return error.message;
-    if (typeof error.message === 'string') return error.message;
+    if (!error)
+        return '';
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error && typeof error.message === 'string')
+        return error.message;
+    if (typeof error.message === 'string')
+        return error.message;
     return String(error);
 }
-
 function _safeJson(payload) {
     try {
         return JSON.stringify(payload, null, 2);
-    } catch {
+    }
+    catch {
         return '{"kind":"ZENITH_RUNTIME_ERROR","message":"Unable to serialize runtime error payload"}';
     }
 }
-
+function _readProcessEnv(name) {
+    const runtime = typeof globalThis !== 'undefined' ? globalThis : {};
+    const runtimeProcess = typeof process !== 'undefined'
+        ? process
+        : runtime.process;
+    if (!runtimeProcess || typeof runtimeProcess !== 'object' || !runtimeProcess.env) {
+        return undefined;
+    }
+    const value = runtimeProcess.env[name];
+    return typeof value === 'string' ? value : undefined;
+}
+function _shouldLogRuntimeError() {
+    if (_readProcessEnv('ZENITH_LOG_RUNTIME_ERRORS') === '1') {
+        return true;
+    }
+    const isTestMode = _readProcessEnv('NODE_ENV') === 'test'
+        || _readProcessEnv('ZENITH_TEST_MODE') === '1';
+    return !isTestMode;
+}
 function _isDevDiagnosticsMode() {
     const runtime = typeof globalThis !== 'undefined' ? globalThis : {};
     if (runtime.__ZENITH_RUNTIME_DEV__ === true || runtime.__ZENITH_DEV__ === true) {
@@ -98,11 +117,11 @@ function _isDevDiagnosticsMode() {
     }
     return false;
 }
-
 function _renderOverlay(payload) {
-    if (!_isDevDiagnosticsMode()) return;
-    if (typeof document === 'undefined' || !document.body) return;
-
+    if (!_isDevDiagnosticsMode())
+        return;
+    if (typeof document === 'undefined' || !document.body)
+        return;
     let overlay = document.getElementById(OVERLAY_ID);
     if (!overlay) {
         overlay = document.createElement('aside');
@@ -125,7 +144,6 @@ function _renderOverlay(payload) {
         overlay.style.fontSize = '12px';
         overlay.style.lineHeight = '1.45';
         overlay.style.boxShadow = '0 12px 40px rgba(0,0,0,0.45)';
-
         const copyButton = document.createElement('button');
         copyButton.type = 'button';
         copyButton.setAttribute('data-zx-runtime-copy', 'true');
@@ -138,17 +156,14 @@ function _renderOverlay(payload) {
         copyButton.style.cursor = 'pointer';
         copyButton.textContent = 'Copy JSON';
         overlay.appendChild(copyButton);
-
         document.body.appendChild(overlay);
     }
-
     const textLines = [
         'Zenith Runtime Error',
         `phase: ${payload.phase}`,
         `code: ${payload.code}`,
         `message: ${payload.message}`
     ];
-
     if (payload.marker) {
         textLines.push(`marker: ${payload.marker.type}#${payload.marker.id}`);
     }
@@ -158,10 +173,8 @@ function _renderOverlay(payload) {
     if (payload.hint) {
         textLines.push(`hint: ${payload.hint}`);
     }
-
     const jsonText = _safeJson(payload);
     const panelText = textLines.join('\n');
-
     let pre = overlay.querySelector('pre[data-zx-runtime-error]');
     if (!pre) {
         pre = document.createElement('pre');
@@ -172,7 +185,6 @@ function _renderOverlay(payload) {
         overlay.insertBefore(pre, overlay.firstChild);
     }
     pre.textContent = panelText;
-
     const copyButton = overlay.querySelector('button[data-zx-runtime-copy="true"]');
     if (copyButton) {
         copyButton.onclick = () => {
@@ -183,11 +195,9 @@ function _renderOverlay(payload) {
         };
     }
 }
-
 function _mapLegacyError(error, fallback) {
     const rawMessage = _extractErrorMessage(error);
     const safeMessage = _sanitizeMessage(rawMessage);
-
     const details = {
         phase: VALID_PHASES.has(fallback.phase) ? fallback.phase : 'hydrate',
         code: VALID_CODES.has(fallback.code) ? fallback.code : 'BINDING_APPLY_FAILED',
@@ -196,12 +206,12 @@ function _mapLegacyError(error, fallback) {
         path: _sanitizePath(fallback.path),
         hint: _sanitizeHint(fallback.hint)
     };
-
     if (/failed to resolve expression literal/i.test(rawMessage)) {
         details.phase = 'bind';
         details.code = 'UNRESOLVED_EXPRESSION';
         details.hint = details.hint || 'Verify expression scope keys and signal aliases.';
-    } else if (/non-renderable (object|function)/i.test(rawMessage)) {
+    }
+    else if (/non-renderable (object|function)/i.test(rawMessage)) {
         details.phase = 'render';
         details.code = 'NON_RENDERABLE_VALUE';
         const match = rawMessage.match(/at\s+([A-Za-z0-9_\[\].-]+)/);
@@ -209,7 +219,8 @@ function _mapLegacyError(error, fallback) {
             details.path = _sanitizePath(match[1]);
         }
         details.hint = details.hint || 'Use map() to render object fields into nodes.';
-    } else if (/unresolved .* marker index/i.test(rawMessage)) {
+    }
+    else if (/unresolved .* marker index/i.test(rawMessage)) {
         details.phase = 'bind';
         details.code = 'MARKER_MISSING';
         const markerMatch = rawMessage.match(/unresolved\s+(\w+)\s+marker index\s+(\d+)/i);
@@ -221,40 +232,33 @@ function _mapLegacyError(error, fallback) {
         }
         details.hint = details.hint || 'Confirm SSR markers and client selector tables match.';
     }
-
     return details;
 }
-
 export function isZenithRuntimeError(error) {
-    return !!(
-        error &&
+    return !!(error &&
         typeof error === 'object' &&
         error.zenithRuntimeError &&
-        error.zenithRuntimeError.kind === 'ZENITH_RUNTIME_ERROR'
-    );
+        error.zenithRuntimeError.kind === 'ZENITH_RUNTIME_ERROR');
 }
-
 export function createZenithRuntimeError(details, cause) {
     const phase = VALID_PHASES.has(details?.phase) ? details.phase : 'hydrate';
     const code = VALID_CODES.has(details?.code) ? details.code : 'BINDING_APPLY_FAILED';
     const message = _sanitizeMessage(details?.message || 'Runtime failure');
-
     const payload = {
         kind: 'ZENITH_RUNTIME_ERROR',
         phase,
         code,
         message
     };
-
     const marker = _normalizeMarker(details?.marker);
-    if (marker) payload.marker = marker;
-
+    if (marker)
+        payload.marker = marker;
     const path = _sanitizePath(details?.path);
-    if (path) payload.path = path;
-
+    if (path)
+        payload.path = path;
     const hint = _sanitizeHint(details?.hint);
-    if (hint) payload.hint = hint;
-
+    if (hint)
+        payload.hint = hint;
     const error = new Error(`[Zenith Runtime] ${code}: ${message}`);
     error.name = 'ZenithRuntimeError';
     error.zenithRuntimeError = payload;
@@ -264,23 +268,24 @@ export function createZenithRuntimeError(details, cause) {
     error.toJSON = () => payload;
     return error;
 }
-
 function _reportRuntimeError(error) {
-    if (!error || error.__zenithRuntimeErrorReported === true) return;
+    if (!error || error.__zenithRuntimeErrorReported === true)
+        return;
     error.__zenithRuntimeErrorReported = true;
     const payload = error.zenithRuntimeError;
-    if (payload && typeof console !== 'undefined' && typeof console.error === 'function') {
+    if (payload
+        && _shouldLogRuntimeError()
+        && typeof console !== 'undefined'
+        && typeof console.error === 'function') {
         console.error('[Zenith Runtime]', payload);
     }
     _renderOverlay(payload);
 }
-
 export function throwZenithRuntimeError(details, cause) {
     const error = createZenithRuntimeError(details, cause);
     _reportRuntimeError(error);
     throw error;
 }
-
 export function rethrowZenithRuntimeError(error, fallback = {}) {
     if (isZenithRuntimeError(error)) {
         const payload = error.zenithRuntimeError || {};
@@ -288,7 +293,6 @@ export function rethrowZenithRuntimeError(error, fallback = {}) {
         const marker = !payload.marker ? _normalizeMarker(fallback.marker) : payload.marker;
         const path = !payload.path ? _sanitizePath(fallback.path) : payload.path;
         const hint = !payload.hint ? _sanitizeHint(fallback.hint) : payload.hint;
-
         if (marker || path || hint) {
             updatedPayload = {
                 ...payload,

package/dist/effect.d.ts

@@ -0,0 +1 @@
+export { zeneffect as effect } from "./zeneffect.js";

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare function zenWindow(): Window | null;
+export declare function zenDocument(): Document | null;

package/dist/env.js

@@ -1,22 +1,12 @@
 // ---------------------------------------------------------------------------
-// env.js — Zenith Runtime canonical environment accessors
+// env.ts — Zenith Runtime canonical environment accessors
 // ---------------------------------------------------------------------------
 // SSR-safe access to window and document. Returns null when not in browser.
 // Use zenWindow() / zenDocument() instead of direct window/document access.
 // ---------------------------------------------------------------------------
-
-/**
- * SSR-safe window accessor.
- * @returns {Window | null}
- */
 export function zenWindow() {
     return typeof window === 'undefined' ? null : window;
 }
-
-/**
- * SSR-safe document accessor.
- * @returns {Document | null}
- */
 export function zenDocument() {
     return typeof document === 'undefined' ? null : document;
 }

package/dist/events.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Bind an event listener to a DOM element.
+ *
+ * @param {Element} element - The DOM element
+ * @param {string} eventName - The event name (e.g. "click")
+ * @param {() => any} exprFn - Pre-bound expression function that must resolve to a handler
+ */
+export function bindEvent(element: Element, eventName: string, exprFn: () => any): void;

package/dist/events.js

@@ -14,10 +14,8 @@
 // No delegation.
 // No wrapping.
 // ---------------------------------------------------------------------------
-
 import { _registerListener } from './cleanup.js';
 import { rethrowZenithRuntimeError, throwZenithRuntimeError } from './diagnostics.js';
-
 /**
  * Bind an event listener to a DOM element.
  *
@@ -27,7 +25,6 @@ import { rethrowZenithRuntimeError, throwZenithRuntimeError } from './diagnostic
  */
 export function bindEvent(element, eventName, exprFn) {
     const resolved = exprFn();
-
     if (typeof resolved !== 'function') {
         throwZenithRuntimeError({
             phase: 'bind',
@@ -38,11 +35,11 @@ export function bindEvent(element, eventName, exprFn) {
             hint: 'Bind events to function references.'
         });
     }
-
     const wrapped = function zenithBoundEvent(event) {
         try {
             return resolved.call(this, event);
-        } catch (error) {
+        }
+        catch (error) {
             rethrowZenithRuntimeError(error, {
                 phase: 'event',
                 code: 'EVENT_HANDLER_FAILED',
@@ -53,7 +50,6 @@ export function bindEvent(element, eventName, exprFn) {
             });
         }
     };
-
     element.addEventListener(eventName, wrapped);
     _registerListener(element, eventName, wrapped);
 }

package/dist/hydrate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Hydrate a pre-rendered DOM tree using explicit payload tables.
+ *
+ * @param {{
+ *   ir_version: number,
+ *   root: Document | Element,
+ *   expressions: Array<{ marker_index: number, signal_index?: number|null, state_index?: number|null, component_instance?: string|null, component_binding?: string|null, literal?: string|null }>,
+ *   markers: Array<{ index: number, kind: 'text' | 'attr' | 'event', selector: string, attr?: string }>,
+ *   events: Array<{ index: number, event: string, selector: string }>,
+ *   refs?: Array<{ index: number, state_index: number, selector: string }>,
+ *   state_values: Array<*>,
+ *   state_keys?: Array<string>,
+ *   signals: Array<{ id: number, kind: 'signal', state_index: number }>,
+ *   components?: Array<{ instance: string, selector: string, create: Function }>
+ * }} payload
+ * @returns {() => void}
+ */
+export function hydrate(payload: {
+    ir_version: number;
+    root: Document | Element;
+    expressions: Array<{
+        marker_index: number;
+        signal_index?: number | null;
+        state_index?: number | null;
+        component_instance?: string | null;
+        component_binding?: string | null;
+        literal?: string | null;
+    }>;
+    markers: Array<{
+        index: number;
+        kind: "text" | "attr" | "event";
+        selector: string;
+        attr?: string;
+    }>;
+    events: Array<{
+        index: number;
+        event: string;
+        selector: string;
+    }>;
+    refs?: Array<{
+        index: number;
+        state_index: number;
+        selector: string;
+    }>;
+    state_values: Array<any>;
+    state_keys?: Array<string>;
+    signals: Array<{
+        id: number;
+        kind: "signal";
+        state_index: number;
+    }>;
+    components?: Array<{
+        instance: string;
+        selector: string;
+        create: Function;
+    }>;
+}): () => void;