@zenithbuild/runtime 0.2.0 → 0.5.0-beta.2.3

package/dist/index.js

@@ -0,0 +1,4 @@
+export { signal } from './signal.js';
+export { state } from './state.js';
+export { zeneffect } from './zeneffect.js';
+export { hydrate } from './hydrate.js';

package/dist/ref.js

@@ -0,0 +1,23 @@
+// ---------------------------------------------------------------------------
+// ref.js — Zenith Runtime ref primitive
+// ---------------------------------------------------------------------------
+// A structural DOM pointer. NOT reactive.
+// ref.current is a plain property — no tracking, no proxies, no subscriptions.
+//
+// Contract:
+//   - ref() returns { current: null }
+//   - ref(initialValue) returns { current: initialValue }
+//   - .current is assigned by runtime at mount, before zenMount callbacks run
+//   - .current is set to null on component disposal
+//   - Reading .current does NOT register a dependency in zenEffect
+
+/**
+ * Create a deterministic ref for structural DOM binding.
+ *
+ * @template T
+ * @param {T} [initialValue]
+ * @returns {{ current: T | null }}
+ */
+export function ref(initialValue) {
+    return { current: initialValue ?? null };
+}

package/dist/runtime.js

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// runtime.js — Zenith Runtime V0
+// ---------------------------------------------------------------------------
+// Backward-compatible mount wrapper around explicit hydrate(payload).
+// ---------------------------------------------------------------------------
+
+import { hydrate } from './hydrate.js';
+import { cleanup } from './cleanup.js';
+
+/**
+ * Mount a page module that already contains deterministic binding tables.
+ *
+ * @param {HTMLElement} container
+ * @param {object | function} pageModule
+ * @returns {() => void}
+ */
+export function mount(container, pageModule) {
+    if (!container || typeof container.querySelectorAll !== 'function') {
+        throw new Error('[Zenith Runtime] mount(container, pageModule) requires a DOM container');
+    }
+
+    const pageFactory = _resolvePageFactory(pageModule);
+    if (!pageFactory) {
+        throw new Error('[Zenith Runtime] mount(container, pageModule) requires default() or __zenith_page()');
+    }
+
+    const page = pageFactory();
+    if (!page || typeof page.html !== 'string') {
+        throw new Error('[Zenith Runtime] __zenith_page() must return an object with html');
+    }
+
+    container.innerHTML = page.html;
+
+    hydrate({
+        root: container,
+        ir_version: page.ir_version,
+        expressions: Array.isArray(page.expressions) ? page.expressions : [],
+        markers: Array.isArray(page.markers) ? page.markers : [],
+        events: Array.isArray(page.events) ? page.events : [],
+        state_values: Array.isArray(page.state_values) ? page.state_values : [],
+        signals: Array.isArray(page.signals) ? page.signals : [],
+        components: Array.isArray(page.components) ? page.components : []
+    });
+
+    return function unmount() {
+        cleanup();
+        container.innerHTML = '';
+    };
+}
+
+function _resolvePageFactory(pageModule) {
+    if (typeof pageModule === 'function') return pageModule;
+    if (!pageModule || typeof pageModule !== 'object') return null;
+    if (typeof pageModule.default === 'function') return pageModule.default;
+    if (typeof pageModule.__zenith_page === 'function') return pageModule.__zenith_page;
+    return null;
+}

package/dist/signal.js

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// signal.js — Zenith Runtime V0
+// ---------------------------------------------------------------------------
+// Minimal explicit signal primitive.
+//
+// API:
+//   const count = signal(0);
+//   count.get();
+//   count.set(1);
+//   const unsubscribe = count.subscribe((value) => { ... });
+//
+// Constraints:
+//   - No proxy
+//   - No implicit dependency tracking
+//   - No scheduler
+//   - No async queue
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a deterministic signal with explicit subscription semantics.
+ *
+ * @param {*} initialValue
+ * @returns {{ get: () => *, set: (next: *) => *, subscribe: (fn: (value: *) => void) => () => void }}
+ */
+export function signal(initialValue) {
+    let value = initialValue;
+    const subscribers = new Set();
+
+    return {
+        get() {
+            return value;
+        },
+        set(nextValue) {
+            if (Object.is(value, nextValue)) {
+                return value;
+            }
+
+            value = nextValue;
+
+            const snapshot = [...subscribers];
+            for (let i = 0; i < snapshot.length; i++) {
+                snapshot[i](value);
+            }
+
+            return value;
+        },
+        subscribe(fn) {
+            if (typeof fn !== 'function') {
+                throw new Error('[Zenith Runtime] signal.subscribe(fn) requires a function');
+            }
+
+            subscribers.add(fn);
+            return function unsubscribe() {
+                subscribers.delete(fn);
+            };
+        }
+    };
+}

package/dist/state.js

@@ -0,0 +1,79 @@
+// ---------------------------------------------------------------------------
+// state.js — Zenith Runtime V0
+// ---------------------------------------------------------------------------
+// Proxy-free immutable state helper.
+//
+// API:
+//   const store = state({ count: 0 });
+//   store.get();
+//   store.set({ count: 1 });
+//   store.set((prev) => ({ ...prev, count: prev.count + 1 }));
+// ---------------------------------------------------------------------------
+import { _nextReactiveId, _trackDependency } from './zeneffect.js';
+
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+function cloneSnapshot(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    if (isPlainObject(value)) {
+        return { ...value };
+    }
+    return value;
+}
+
+/**
+ * Create a proxy-free immutable state container.
+ *
+ * @param {object} initialValue
+ * @returns {{ get: () => object, set: (patch: object | ((prev: object) => object)) => object, subscribe: (fn: (next: object) => void) => () => void }}
+ */
+export function state(initialValue) {
+    let current = Object.freeze(cloneSnapshot(initialValue));
+    const subscribers = new Set();
+
+    return {
+        get() {
+            return current;
+        },
+        set(nextPatch) {
+            const nextValue = typeof nextPatch === 'function'
+                ? nextPatch(current)
+                : { ...current, ...nextPatch };
+
+            if (!nextValue || typeof nextValue !== 'object' || Array.isArray(nextValue)) {
+                throw new Error('[Zenith Runtime] state.set(next) must resolve to a plain object');
+            }
+
+            const nextSnapshot = Object.freeze(cloneSnapshot(nextValue));
+            if (Object.is(current, nextSnapshot)) {
+                return current;
+            }
+
+            current = nextSnapshot;
+
+            const snapshot = [...subscribers];
+            for (let i = 0; i < snapshot.length; i++) {
+                snapshot[i](current);
+            }
+
+            return current;
+        },
+        subscribe(fn) {
+            if (typeof fn !== 'function') {
+                throw new Error('[Zenith Runtime] state.subscribe(fn) requires a function');
+            }
+
+            subscribers.add(fn);
+            return function unsubscribe() {
+                subscribers.delete(fn);
+            };
+        }
+    };
+}

package/dist/template.js

@@ -0,0 +1,360 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function normalizeNewlines(value) {
+    return String(value).replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+function readRuntimeSourceFile(fileName) {
+    const fullPath = join(__dirname, fileName);
+    return normalizeNewlines(readFileSync(fullPath, 'utf8'));
+}
+
+function stripImports(source) {
+    return source.replace(/^\s*import\s+[^;]+;\s*$/gm, '').trim();
+}
+
+function buildRuntimeModuleSource() {
+    const segments = [
+        stripImports(readRuntimeSourceFile('zeneffect.js')),
+        stripImports(readRuntimeSourceFile('ref.js')),
+        stripImports(readRuntimeSourceFile('signal.js')),
+        stripImports(readRuntimeSourceFile('state.js')),
+        stripImports(readRuntimeSourceFile('diagnostics.js')),
+        stripImports(readRuntimeSourceFile('cleanup.js')),
+        stripImports(readRuntimeSourceFile('hydrate.js'))
+    ].filter(Boolean);
+
+    return normalizeNewlines(segments.join('\n\n'));
+}
+
+const RUNTIME_MODULE_SOURCE = buildRuntimeModuleSource();
+
+export function runtimeModuleSource() {
+    return RUNTIME_MODULE_SOURCE;
+}
+
+const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return;
+  if (window.__zenithDevClientActive === true) return;
+  window.__zenithDevClientActive = true;
+
+  const DEV_KEY = '__ZENITH_DEV__';
+  const STORAGE_KEY = '__ZENITH_DEBUG__';
+  const DEFAULT_LOGS = { route: false, bindings: false, events: false, hmr: false };
+
+  function readStoredLogs() {
+    try {
+      const raw = window.localStorage.getItem(STORAGE_KEY);
+      if (!raw) return { ...DEFAULT_LOGS };
+      if (raw === '1') return { route: true, bindings: true, events: true, hmr: true };
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object') return { ...DEFAULT_LOGS };
+      return {
+        route: parsed.route === true,
+        bindings: parsed.bindings === true,
+        events: parsed.events === true,
+        hmr: parsed.hmr === true
+      };
+    } catch {
+      return { ...DEFAULT_LOGS };
+    }
+  }
+
+  function persistLogs(logs) {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(logs));
+    } catch {
+      // ignore storage failures in private mode
+    }
+  }
+
+  function ensureDevState() {
+    const current = window[DEV_KEY] && typeof window[DEV_KEY] === 'object' ? window[DEV_KEY] : {};
+    const logs = current.logs && typeof current.logs === 'object' ? current.logs : readStoredLogs();
+    const overlay = current.overlay && typeof current.overlay === 'object' ? current.overlay : {};
+    const state = {
+      logs: {
+        route: logs.route === true,
+        bindings: logs.bindings === true,
+        events: logs.events === true,
+        hmr: logs.hmr === true
+      },
+      overlay: {
+        open: overlay.open === true
+      }
+    };
+    window[DEV_KEY] = state;
+    persistLogs(state.logs);
+    return state;
+  }
+
+  function parseEventData(raw) {
+    if (typeof raw !== 'string' || raw.length === 0) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+
+  function fetchDevState() {
+    return fetch('/__zenith_dev/state', { cache: 'no-store' })
+      .then(function (response) {
+        if (!response || !response.ok) {
+          return null;
+        }
+        return response.json().catch(function () { return null; });
+      })
+      .then(function (payload) {
+        return payload && typeof payload === 'object' ? payload : null;
+      })
+      .catch(function () {
+        return null;
+      });
+  }
+
+  function swapStylesheet(nextHref) {
+    if (typeof nextHref !== 'string' || nextHref.length === 0) {
+      window.location.reload();
+      return;
+    }
+    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
+    if (links.length === 0) {
+      window.location.reload();
+      return;
+    }
+    const separator = nextHref.includes('?') ? '&' : '?';
+    links[0].setAttribute('href', nextHref + separator + '__zenith_dev=' + Date.now());
+  }
+
+  const state = ensureDevState();
+  const shell = document.createElement('div');
+  shell.setAttribute('data-zenith-dev-overlay', 'true');
+  shell.style.position = 'fixed';
+  shell.style.left = '12px';
+  shell.style.bottom = '12px';
+  shell.style.zIndex = '2147483647';
+  shell.style.fontFamily = 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace';
+  shell.style.fontSize = '12px';
+  shell.style.pointerEvents = 'none';
+
+  const pill = document.createElement('button');
+  pill.type = 'button';
+  pill.textContent = 'Zenith Dev';
+  pill.style.pointerEvents = 'auto';
+  pill.style.border = '1px solid rgba(255,255,255,0.2)';
+  pill.style.background = 'rgba(20,20,24,0.88)';
+  pill.style.color = '#ecf2ff';
+  pill.style.borderRadius = '999px';
+  pill.style.padding = '6px 10px';
+  pill.style.cursor = 'pointer';
+  pill.style.boxShadow = '0 8px 24px rgba(0,0,0,0.25)';
+
+  const panel = document.createElement('div');
+  panel.style.display = state.overlay.open ? 'block' : 'none';
+  panel.style.width = '360px';
+  panel.style.marginTop = '8px';
+  panel.style.pointerEvents = 'auto';
+  panel.style.background = 'rgba(14,16,20,0.94)';
+  panel.style.color = '#dbe6ff';
+  panel.style.border = '1px solid rgba(255,255,255,0.16)';
+  panel.style.borderRadius = '10px';
+  panel.style.padding = '10px';
+  panel.style.boxShadow = '0 14px 30px rgba(0,0,0,0.35)';
+
+  const status = document.createElement('div');
+  status.textContent = 'status: connecting';
+  status.style.marginBottom = '6px';
+
+  const info = document.createElement('div');
+  info.textContent = 'route: ' + window.location.pathname;
+  info.style.opacity = '0.85';
+  info.style.marginBottom = '8px';
+  info.style.whiteSpace = 'pre-wrap';
+
+  const controls = document.createElement('div');
+  controls.style.display = 'grid';
+  controls.style.gridTemplateColumns = '1fr 1fr';
+  controls.style.gap = '6px';
+  controls.style.marginBottom = '8px';
+
+  function makeButton(label) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = label;
+    button.style.border = '1px solid rgba(255,255,255,0.2)';
+    button.style.borderRadius = '6px';
+    button.style.padding = '6px 8px';
+    button.style.cursor = 'pointer';
+    button.style.background = 'rgba(36,41,51,0.85)';
+    button.style.color = '#ecf2ff';
+    return button;
+  }
+
+  const reloadButton = makeButton('Reload');
+  const copyButton = makeButton('Copy URL');
+  const debugButton = makeButton('Toggle Debug');
+  const overlayButton = makeButton('Toggle Overlay');
+
+  controls.append(reloadButton, copyButton, debugButton, overlayButton);
+
+  const logs = document.createElement('pre');
+  logs.style.margin = '0';
+  logs.style.padding = '8px';
+  logs.style.maxHeight = '190px';
+  logs.style.overflow = 'auto';
+  logs.style.border = '1px solid rgba(255,255,255,0.12)';
+  logs.style.borderRadius = '6px';
+  logs.style.background = 'rgba(8,10,14,0.8)';
+  logs.style.whiteSpace = 'pre-wrap';
+  logs.textContent = '[zenith-dev] waiting for server events...';
+
+  panel.append(status, info, controls, logs);
+  shell.append(pill, panel);
+
+  function setOpen(open) {
+    state.overlay.open = open === true;
+    panel.style.display = state.overlay.open ? 'block' : 'none';
+  }
+
+  function appendLog(line) {
+    logs.textContent += '\\n' + line;
+    logs.scrollTop = logs.scrollHeight;
+  }
+
+  function updateInfo(payload) {
+    const route = typeof payload.route === 'string' ? payload.route : window.location.pathname;
+    const hash = typeof payload.buildHash === 'string' ? payload.buildHash : 'n/a';
+    const durationValue = Number.isFinite(payload.durationMs) ? payload.durationMs : payload.lastBuildMs;
+    const duration = Number.isFinite(durationValue) ? durationValue + 'ms' : 'n/a';
+    const changed = Array.isArray(payload.changedFiles) ? payload.changedFiles.join(', ') : '';
+    const serverUrl = typeof payload.serverUrl === 'string' ? payload.serverUrl : window.location.origin;
+    const buildId = Number.isInteger(payload.buildId) ? payload.buildId : 'n/a';
+    const buildStatus = typeof payload.status === 'string' ? payload.status : 'unknown';
+    info.textContent =
+      'server: ' + serverUrl + '\\n' +
+      'route: ' + route + '\\n' +
+      'buildId: ' + buildId + '\\n' +
+      'status: ' + buildStatus + '\\n' +
+      'hash: ' + hash + '\\n' +
+      'duration: ' + duration + '\\n' +
+      'changed: ' + changed;
+  }
+
+  function allLogsEnabled() {
+    return state.logs.route && state.logs.bindings && state.logs.events && state.logs.hmr;
+  }
+
+  function setAllLogs(enabled) {
+    state.logs.route = enabled;
+    state.logs.bindings = enabled;
+    state.logs.events = enabled;
+    state.logs.hmr = enabled;
+    persistLogs(state.logs);
+    appendLog('[zenith-dev] debug logs ' + (enabled ? 'enabled' : 'disabled'));
+  }
+
+  function emitDebug(label, payload) {
+    if (state.logs.hmr === true) {
+      console.log('[zenith-dev] ' + label, payload);
+    }
+  }
+
+  pill.addEventListener('click', function () {
+    setOpen(!state.overlay.open);
+  });
+  overlayButton.addEventListener('click', function () {
+    setOpen(!state.overlay.open);
+  });
+  reloadButton.addEventListener('click', function () {
+    window.location.reload();
+  });
+  copyButton.addEventListener('click', function () {
+    const target = window.location.origin;
+    if (navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
+      navigator.clipboard.writeText(target).catch(() => {});
+    }
+    appendLog('[zenith-dev] copied ' + target);
+  });
+  debugButton.addEventListener('click', function () {
+    setAllLogs(!allLogsEnabled());
+  });
+
+  function mount() {
+    if (document.body) {
+      document.body.appendChild(shell);
+    }
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', mount, { once: true });
+  } else {
+    mount();
+  }
+
+  const source = new EventSource('/__zenith_dev/events');
+  source.addEventListener('connected', function (event) {
+    const payload = parseEventData(event.data);
+    status.textContent = 'status: connected';
+    updateInfo(payload);
+    appendLog('[connected] dev channel online');
+    emitDebug('connected', payload);
+    fetchDevState().then(function (statePayload) {
+      if (!statePayload) return;
+      updateInfo({ ...payload, ...statePayload });
+    });
+  });
+  source.addEventListener('build_start', function (event) {
+    const payload = parseEventData(event.data);
+    status.textContent = 'status: rebuilding';
+    appendLog('[build_start] ' + (Array.isArray(payload.changedFiles) ? payload.changedFiles.join(', ') : ''));
+    emitDebug('build_start', payload);
+  });
+  source.addEventListener('build_complete', function (event) {
+    const payload = parseEventData(event.data);
+    status.textContent = 'status: ready';
+    updateInfo(payload);
+    appendLog('[build_complete] ' + (Number.isFinite(payload.durationMs) ? payload.durationMs + 'ms' : 'done'));
+    emitDebug('build_complete', payload);
+  });
+  source.addEventListener('build_error', function (event) {
+    const payload = parseEventData(event.data);
+    status.textContent = 'status: error';
+    appendLog('[build_error] ' + (payload.message || 'Unknown error'));
+    emitDebug('build_error', payload);
+  });
+  source.addEventListener('reload', function (event) {
+    const payload = parseEventData(event.data);
+    appendLog('[reload] refreshing page');
+    emitDebug('reload', payload);
+    setTimeout(function () {
+      window.location.reload();
+    }, 30);
+  });
+  source.addEventListener('css_update', function (event) {
+    const payload = parseEventData(event.data);
+    appendLog('[css_update] ' + (payload.href || ''));
+    emitDebug('css_update', payload);
+    fetchDevState().then(function (statePayload) {
+      if (statePayload && typeof statePayload.cssHref === 'string' && statePayload.cssHref.length > 0) {
+        updateInfo({ ...payload, ...statePayload });
+        swapStylesheet(statePayload.cssHref);
+        return;
+      }
+      swapStylesheet(payload.href);
+    });
+  });
+  source.addEventListener('error', function () {
+    status.textContent = 'status: disconnected';
+    appendLog('[error] lost dev server connection');
+  });
+})();`;
+
+export function runtimeDevClientSource() {
+    return RUNTIME_DEV_CLIENT_SOURCE;
+}