@zenithbuild/runtime 0.2.0 → 0.5.0-beta.2.3

package/HYDRATION_CONTRACT.md

@@ -0,0 +1,98 @@
+# Zenith Runtime V0 Hydration Contract
+
+Status: FROZEN (V0)
+
+This contract locks hydration and reactivity boundaries for Zenith V0.
+
+## 1. No Runtime Discovery
+
+Runtime must not discover bindings by scanning unknown DOM structure.
+
+Allowed:
+- Resolve selectors from bundler-provided marker/event tables.
+
+Forbidden:
+- Global `querySelectorAll('*')` discovery passes.
+- Runtime inference of binding intent from HTML shape.
+
+## 2. No Implicit Reactivity
+
+Runtime primitives are explicit:
+- `signal(initial)`
+- `state(initialObject)`
+- `zeneffect(dependencies, fn)`
+
+Forbidden:
+- Proxy-based tracking.
+- Implicit dependency capture contexts.
+- Scheduler/queue abstractions.
+
+## 3. Deterministic Ordering
+
+Compiler expression ordering is canonical.
+Bundler and runtime must preserve index semantics exactly.
+
+Required:
+- Marker indices are sequential `0..N-1`.
+- Marker count equals expression table length.
+- Runtime never remaps indices.
+
+## 4. Explicit Bootstrap
+
+Hydration is explicit and called by bundler bootstrap only:
+
+```js
+hydrate({
+  ir_version: 1,
+  root: document,
+  expressions: __zenith_expr,
+  markers: __zenith_markers,
+  events: __zenith_events,
+  state_values: __zenith_state_values,
+  signals: __zenith_signals,
+  components: __zenith_components
+});
+```
+
+Runtime must export functions only. Runtime must not auto-run.
+
+## 5. Component Factory Payload
+
+Component scripts are compile-time hoisted and emitted as factory modules.
+Runtime receives only explicit component references in `payload.components`.
+
+Required:
+- Component host selectors are provided by bundler.
+- Runtime instantiates factories only from payload.
+- Runtime merges returned `bindings` into hydration state by instance key.
+
+Forbidden:
+- Runtime component discovery by scanning unknown DOM shape.
+- Runtime-generated component wrappers or lifecycle registries.
+
+## 6. Hard Fail Semantics
+
+Runtime must throw for contract drift:
+- Missing or unsupported `ir_version`.
+- Duplicate marker indices.
+- Missing index in sequence.
+- Out-of-order expression table entries.
+- Out-of-order marker table entries.
+- Marker index out of bounds.
+- Marker/expression count mismatch.
+- Event index out of bounds.
+
+No fallback behavior is allowed for broken payload contracts.
+
+## 7. Determinism and Purity
+
+Forbidden in runtime/bundler output:
+- `eval(`
+- `new Function(`
+- `require(`
+- `Date(`
+- `Math.random(`
+- `crypto.randomUUID(`
+- `process.env`
+
+Compile-time guarantees override runtime flexibility.

package/README.md

@@ -1,5 +1,8 @@
 # @zenith/runtime
 
+> **⚠️ Internal API:** This package is an internal implementation detail of the Zenith framework. It is not intended for public use and its API may break without warning. Please use `@zenithbuild/core` instead.
+
+
 The core runtime library for the Zenith framework.
 
 ## Overview

package/RUNTIME_CONTRACT.md

@@ -0,0 +1,183 @@
+# RUNTIME_CONTRACT.md — Sealed Runtime Interface
+
+> **This document is a legal boundary.**
+> The runtime is a consumer of bundler output.
+> It does not reinterpret, normalize, or extend.
+
+## Status: FROZEN (V0)
+
+---
+
+## 1. Input Surface
+
+The runtime receives exactly one module per page:
+
+| Export | Type | Contract |
+|---|---|---|
+| `__zenith_html` | `string` | Template literal, immutable |
+| `__zenith_expr` | `(() => any)[]` | Pre-bound expression functions, immutable, ordered |
+| `__zenith_page()` | `function` | Returns `{ html, expressions }` |
+
+### Expression Functions
+
+Each entry in `__zenith_expr` is a **pre-bound zero-argument function** emitted by the bundler. The runtime never resolves expression strings, never performs key lookups, and never interprets JavaScript.
+
+```js
+// Bundler emits:
+export const __zenith_expr = [
+  () => count(),
+  () => count() + 1,
+  () => increment()
+];
+
+export default function __zenith_page() {
+  return {
+    html: __zenith_html,
+    expressions: __zenith_expr
+  };
+}
+```
+
+The runtime simply executes: `expressions[index]()`.
+
+---
+
+## 2. Runtime Responsibilities (Allowed)
+
+| Action | Method |
+|---|---|
+| Insert HTML into container | `container.innerHTML = html` |
+| Locate expression bindings | `querySelectorAll('[data-zx-e]')` |
+| Locate event bindings | `querySelectorAll('[data-zx-on-*]')` |
+| Bind expressions to DOM | `effect(() => node.textContent = expressions[index]())` |
+| Bind event listeners | `node.addEventListener(event, expressions[index])` |
+| Update DOM on signal change | Via effect re-execution |
+| Clean up on unmount | Remove effects + listeners |
+
+---
+
+## 3. Runtime Prohibitions (Forbidden)
+
+The runtime **must never**:
+
+- Parse JavaScript expressions
+- Resolve expression strings against a scope object
+- Normalize expression strings
+- Modify expression content
+- Introduce component abstractions
+- Perform virtual DOM diffing
+- Re-render full subtrees
+- Implement lifecycle hooks beyond mount/unmount
+- Access or mutate `window` globals
+- Reorder binding indices
+- Interpret import semantics
+- Add framework-level abstractions (routing, stores, context)
+
+---
+
+## 4. Data Attribute Contract
+
+Inherited from `BUNDLER_CONTRACT.md`:
+
+| Attribute | Format | Runtime Action |
+|---|---|---|
+| `data-zx-e` | `"<index>"` or `"<i0> <i1> ..."` | Execute `expressions[index]()`, bind result to node |
+| `data-zx-on-<event>` | `"<index>"` | Call `addEventListener(event, expressions[index])` |
+
+Index values are 0-based integers matching `__zenith_expr` array positions.
+
+---
+
+## 5. Reactivity Model
+
+### Signal Primitive
+
+```js
+const count = signal(0);  // Create
+count();                   // Read (tracks dependency)
+count.set(1);              // Write (notifies subscribers)
+```
+
+Internals:
+- Each signal maintains a `Set<Effect>` of subscribers
+- Reading a signal during effect execution registers the effect as a subscriber
+- Writing a signal notifies all subscribers synchronously
+
+### Effect Primitive
+
+```js
+effect(() => {
+  node.textContent = count();
+});
+```
+
+Internals:
+- On execution, sets itself as the "current tracking context"
+- Any signal read during execution adds this effect to its subscriber set
+- When a dependency signal changes, the effect re-runs
+
+### Constraints
+
+- No batching
+- No scheduler / microtask queue
+- No async effects
+- No suspense / lazy loading
+- No lifecycle hooks beyond `cleanup()`
+
+---
+
+## 6. Hydration Algorithm
+
+Single-pass, deterministic:
+
+1. Call `__zenith_page()` → receive `{ html, expressions }`
+2. Set `container.innerHTML = html`
+3. Walk DOM once: `querySelectorAll('[data-zx-e], [data-zx-on-click], ...')`
+4. For each node with `data-zx-e`:
+   - Parse space-separated indices
+   - For each index: create `effect(() => node.textContent = expressions[index]())`
+5. For each node with `data-zx-on-*`:
+   - Extract event name from attribute suffix
+   - `node.addEventListener(eventName, expressions[index])`
+6. Store all effects and listeners in a cleanup registry
+
+No recursive diffing. No re-render cycle. No component tree.
+
+---
+
+## 7. Cleanup Contract
+
+The runtime exposes `cleanup()`:
+
+- Disposes all active effects (clears subscriber sets)
+- Removes all event listeners
+- Clears the binding registry
+- Leaves the DOM intact (caller decides whether to clear container)
+
+Cleanup is deterministic — calling it twice is a no-op.
+
+---
+
+## 8. Public API Surface
+
+Total exports (exhaustive):
+
+```js
+export { signal }    // Create reactive signal
+export { effect }    // Create reactive effect
+export { mount }     // Mount page module into container
+export { cleanup }   // Tear down all bindings
+```
+
+Four functions. No more.
+
+---
+
+## 9. Alignment Verification
+
+This contract is valid if and only if:
+
+- [ ] `data-zx-e` indices match `__zenith_expr` array positions (from `BUNDLER_CONTRACT.md` §2)
+- [ ] Expression functions are pre-bound at bundle time — runtime never resolves strings
+- [ ] HMR footer is ignored by runtime (from `BUNDLER_CONTRACT.md` §7)
+- [ ] No symbol beyond `__zenith_html`, `__zenith_expr`, `__zenith_page` is consumed (from `BUNDLER_CONTRACT.md` §1)

package/dist/cleanup.js

@@ -0,0 +1,88 @@
+// ---------------------------------------------------------------------------
+// cleanup.js — Zenith Runtime V0
+// ---------------------------------------------------------------------------
+// Deterministic teardown system.
+//
+// Tracks:
+//   - Active effect disposers
+//   - Active event listeners
+//
+// 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.
+ *
+ * @param {function} dispose
+ */
+export function _registerDisposer(dispose) {
+    _disposers.push(dispose);
+    _cleaned = false;
+}
+
+/**
+ * Register an event listener for later cleanup.
+ *
+ * @param {Element} element
+ * @param {string} event
+ * @param {function} handler
+ */
+export function _registerListener(element, event, handler) {
+    _listeners.push({ element, event, handler });
+    _cleaned = false;
+}
+
+/**
+ * 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() {
+    // Global zenMount/zenEffect registrations can be created outside hydrate's
+    // disposer table (e.g. page-level component bootstraps). Even when cleanup
+    // has already run once, we still need to reset that scope deterministically.
+    if (_cleaned) {
+        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 }}
+ */
+export function _getCounts() {
+    return {
+        effects: _disposers.length,
+        listeners: _listeners.length
+    };
+}

package/dist/diagnostics.js

@@ -0,0 +1,309 @@
+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',
+    'NON_RENDERABLE_VALUE',
+    'MARKER_MISSING',
+    'FRAGMENT_MOUNT_FAILED',
+    'BINDING_APPLY_FAILED',
+    'EVENT_HANDLER_FAILED'
+]);
+
+function _truncate(input, maxLength) {
+    const text = String(input ?? '');
+    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>')
+        .replace(/\/Users\/[^\s"'`]+/g, '<path>')
+        .replace(/\/home\/[^\s"'`]+/g, '<path>')
+        .replace(/\/private\/[^\s"'`]+/g, '<path>')
+        .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;
+    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;
+    return _truncate(compact, MAX_PATH_LENGTH);
+}
+
+function _normalizeMarker(marker) {
+    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 (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;
+    return String(error);
+}
+
+function _safeJson(payload) {
+    try {
+        return JSON.stringify(payload, null, 2);
+    } catch {
+        return '{"kind":"ZENITH_RUNTIME_ERROR","message":"Unable to serialize runtime error payload"}';
+    }
+}
+
+function _isDevDiagnosticsMode() {
+    const runtime = typeof globalThis !== 'undefined' ? globalThis : {};
+    if (runtime.__ZENITH_RUNTIME_DEV__ === true || runtime.__ZENITH_DEV__ === true) {
+        return true;
+    }
+    if (runtime.__ZENITH_RUNTIME_DEV__ === false || runtime.__ZENITH_DEV__ === false) {
+        return false;
+    }
+    if (runtime.__ZENITH_RUNTIME_PROD__ === true) {
+        return false;
+    }
+    if (typeof location !== 'undefined' && location && typeof location.hostname === 'string') {
+        const host = String(location.hostname).toLowerCase();
+        if (host === 'localhost' || host === '127.0.0.1' || host === '[::1]') {
+            return true;
+        }
+    }
+    return false;
+}
+
+function _renderOverlay(payload) {
+    if (!_isDevDiagnosticsMode()) return;
+    if (typeof document === 'undefined' || !document.body) return;
+
+    let overlay = document.getElementById(OVERLAY_ID);
+    if (!overlay) {
+        overlay = document.createElement('aside');
+        overlay.id = OVERLAY_ID;
+        overlay.setAttribute('role', 'alert');
+        overlay.setAttribute('aria-live', 'assertive');
+        overlay.style.position = 'fixed';
+        overlay.style.left = '12px';
+        overlay.style.right = '12px';
+        overlay.style.bottom = '12px';
+        overlay.style.maxHeight = '45vh';
+        overlay.style.overflow = 'auto';
+        overlay.style.zIndex = '2147483647';
+        overlay.style.padding = '12px';
+        overlay.style.border = '1px solid #ff6b6b';
+        overlay.style.borderRadius = '8px';
+        overlay.style.background = '#111';
+        overlay.style.color = '#ffe5e5';
+        overlay.style.fontFamily = 'ui-monospace, SFMono-Regular, Menlo, monospace';
+        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');
+        copyButton.style.marginTop = '8px';
+        copyButton.style.padding = '4px 8px';
+        copyButton.style.border = '1px solid #ff9d9d';
+        copyButton.style.borderRadius = '4px';
+        copyButton.style.background = '#2a2a2a';
+        copyButton.style.color = '#ffe5e5';
+        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}`);
+    }
+    if (payload.path) {
+        textLines.push(`path: ${payload.path}`);
+    }
+    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');
+        pre.setAttribute('data-zx-runtime-error', 'true');
+        pre.style.margin = '0';
+        pre.style.whiteSpace = 'pre-wrap';
+        pre.style.wordBreak = 'break-word';
+        overlay.insertBefore(pre, overlay.firstChild);
+    }
+    pre.textContent = panelText;
+
+    const copyButton = overlay.querySelector('button[data-zx-runtime-copy="true"]');
+    if (copyButton) {
+        copyButton.onclick = () => {
+            const clipboard = typeof navigator !== 'undefined' ? navigator.clipboard : null;
+            if (clipboard && typeof clipboard.writeText === 'function') {
+                void clipboard.writeText(jsonText);
+            }
+        };
+    }
+}
+
+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',
+        message: _sanitizeMessage(fallback.message || safeMessage),
+        marker: _normalizeMarker(fallback.marker),
+        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)) {
+        details.phase = 'render';
+        details.code = 'NON_RENDERABLE_VALUE';
+        const match = rawMessage.match(/at\s+([A-Za-z0-9_\[\].-]+)/);
+        if (match && !details.path) {
+            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)) {
+        details.phase = 'bind';
+        details.code = 'MARKER_MISSING';
+        const markerMatch = rawMessage.match(/unresolved\s+(\w+)\s+marker index\s+(\d+)/i);
+        if (markerMatch && !details.marker) {
+            details.marker = {
+                type: `data-zx-${markerMatch[1]}`,
+                id: Number(markerMatch[2])
+            };
+        }
+        details.hint = details.hint || 'Confirm SSR markers and client selector tables match.';
+    }
+
+    return details;
+}
+
+export function isZenithRuntimeError(error) {
+    return !!(
+        error &&
+        typeof error === 'object' &&
+        error.zenithRuntimeError &&
+        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;
+
+    const path = _sanitizePath(details?.path);
+    if (path) payload.path = path;
+
+    const hint = _sanitizeHint(details?.hint);
+    if (hint) payload.hint = hint;
+
+    const error = new Error(`[Zenith Runtime] ${code}: ${message}`);
+    error.name = 'ZenithRuntimeError';
+    error.zenithRuntimeError = payload;
+    if (cause !== undefined) {
+        error.cause = cause;
+    }
+    error.toJSON = () => payload;
+    return error;
+}
+
+function _reportRuntimeError(error) {
+    if (!error || error.__zenithRuntimeErrorReported === true) return;
+    error.__zenithRuntimeErrorReported = true;
+    const payload = error.zenithRuntimeError;
+    if (payload && 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 || {};
+        let updatedPayload = payload;
+        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,
+                ...(marker ? { marker } : null),
+                ...(path ? { path } : null),
+                ...(hint ? { hint } : null)
+            };
+            error.zenithRuntimeError = updatedPayload;
+            error.toJSON = () => updatedPayload;
+        }
+        _reportRuntimeError(error);
+        throw error;
+    }
+    const mapped = _mapLegacyError(error, fallback || {});
+    const wrapped = createZenithRuntimeError(mapped, error);
+    _reportRuntimeError(wrapped);
+    throw wrapped;
+}

package/dist/effect.js

@@ -0,0 +1,3 @@
+// Deprecated compatibility shim.
+// Runtime V0 contract uses explicit `zeneffect(deps, fn)`.
+export { zeneffect as effect } from './zeneffect.js';