@zenithbuild/runtime 0.5.0-beta.2.5 → 0.6.0

package/HYDRATION_CONTRACT.md

@@ -1,5 +1,8 @@
 # Zenith Runtime V0 Hydration Contract
 
+Canonical public docs: `../zenith-docs/documentation/contracts/hydration-contract.md`
+
+
 Status: FROZEN (V0)
 
 This contract locks hydration and reactivity boundaries for Zenith V0.
@@ -96,3 +99,17 @@ Forbidden in runtime/bundler output:
 - `process.env`
 
 Compile-time guarantees override runtime flexibility.
+
+## 8. Freeze Boundary Contract
+
+Runtime payload freezing is allowed only for deterministic internal tables and
+plain JSON-like containers controlled by runtime (`Object` / `Array`).
+
+Runtime MUST NOT freeze:
+- `ref()` objects (objects with writable `.current`)
+- function values (handlers/callbacks)
+- host/platform objects (`Node`, `EventTarget`, `URL`, `Request`, `Response`, etc.)
+
+Rationale:
+- hydration and `zenMount` must be able to assign `ref.current` without throwing
+- host objects preserve platform mutability semantics

package/README.md

@@ -5,6 +5,12 @@
 
 The core runtime library for the Zenith framework.
 
+## Canonical Docs
+
+- Runtime contract: `../zenith-docs/documentation/contracts/runtime-contract.md`
+- Hydration contract: `../zenith-docs/documentation/contracts/hydration-contract.md`
+- Reactive binding model: `../zenith-docs/documentation/reference/reactive-binding-model.md`
+
 ## Overview
 This package provides the reactivity system, hydration logic, and Virtual DOM primitives used by Zenith applications. It is designed to be lightweight, fast, and tree-shakeable.
 

package/RUNTIME_CONTRACT.md

@@ -1,5 +1,8 @@
 # RUNTIME_CONTRACT.md — Sealed Runtime Interface
 
+Canonical public docs: `../zenith-docs/documentation/contracts/runtime-contract.md`
+
+
 > **This document is a legal boundary.**
 > The runtime is a consumer of bundler output.
 > It does not reinterpret, normalize, or extend.

package/dist/env.js

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// env.js — 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/hydrate.js

@@ -32,8 +32,6 @@ const BOOLEAN_ATTRIBUTES = new Set([
 const STRICT_MEMBER_CHAIN_LITERAL_RE = /^(?:true|false|null|undefined|[A-Za-z_$][A-Za-z0-9_$]*(\.[A-Za-z_$][A-Za-z0-9_$]*)*)$/;
 const UNSAFE_MEMBER_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
 
-const COMPILED_LITERAL_CACHE = new Map();
-
 /**
  * Hydrate a pre-rendered DOM tree using explicit payload tables.
  *
@@ -43,6 +41,7 @@ const COMPILED_LITERAL_CACHE = new Map();
  *   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 }>,
@@ -55,7 +54,22 @@ export function hydrate(payload) {
     try {
         const normalized = _validatePayload(payload);
         _deepFreezePayload(payload);
-        const { root, expressions, markers, events, stateValues, stateKeys, signals, components, route, params, ssrData, props } = normalized;
+        const {
+            root,
+            expressions,
+            markers,
+            events,
+            refs,
+            stateValues,
+            stateKeys,
+            signals,
+            components,
+            route,
+            params,
+            ssrData,
+            props,
+            exprFns
+        } = normalized;
 
         const componentBindings = Object.create(null);
 
@@ -72,6 +86,23 @@ export function hydrate(payload) {
             signalMap.set(i, candidate);
         }
 
+        const hydratedRefs = [];
+        for (let i = 0; i < refs.length; i++) {
+            const refBinding = refs[i];
+            const targetRef = stateValues[refBinding.state_index];
+            const nodes = _resolveNodes(root, refBinding.selector, refBinding.index, 'ref');
+            targetRef.current = nodes[0] || null;
+            hydratedRefs.push(targetRef);
+        }
+
+        if (hydratedRefs.length > 0) {
+            _registerDisposer(() => {
+                for (let i = 0; i < hydratedRefs.length; i++) {
+                    hydratedRefs[i].current = null;
+                }
+            });
+        }
+
         for (let i = 0; i < components.length; i++) {
             const component = components[i];
             const resolvedProps = Object.freeze(_resolveComponentProps(component.props || [], signalMap, {
@@ -149,7 +180,8 @@ export function hydrate(payload) {
                 params,
                 ssrData,
                 marker.kind,
-                props
+                props,
+                exprFns
             );
             _applyMarkerValue(nodes, marker, value);
         }
@@ -176,7 +208,8 @@ export function hydrate(payload) {
                 params,
                 ssrData,
                 marker.kind,
-                props
+                props,
+                exprFns
             );
             _applyMarkerValue(nodes, marker, value);
         }
@@ -184,13 +217,17 @@ export function hydrate(payload) {
         const dependentMarkersBySignal = new Map();
         for (let i = 0; i < expressions.length; i++) {
             const expression = expressions[i];
-            if (!Number.isInteger(expression.signal_index)) {
+            const signalIndices = _resolveExpressionSignalIndices(expression);
+            if (signalIndices.length === 0) {
                 continue;
             }
-            if (!dependentMarkersBySignal.has(expression.signal_index)) {
-                dependentMarkersBySignal.set(expression.signal_index, []);
+            for (let j = 0; j < signalIndices.length; j++) {
+                const signalIndex = signalIndices[j];
+                if (!dependentMarkersBySignal.has(signalIndex)) {
+                    dependentMarkersBySignal.set(signalIndex, []);
+                }
+                dependentMarkersBySignal.get(signalIndex).push(expression.marker_index);
             }
-            dependentMarkersBySignal.get(expression.signal_index).push(expression.marker_index);
         }
 
         for (const [signalId, markerIndexes] of dependentMarkersBySignal.entries()) {
@@ -246,6 +283,7 @@ export function hydrate(payload) {
         }
 
         const eventIndices = new Set();
+        const escDispatchEntries = [];
         for (let i = 0; i < events.length; i++) {
             const eventBinding = events[i];
             if (eventIndices.has(eventBinding.index)) {
@@ -262,7 +300,9 @@ export function hydrate(payload) {
                 componentBindings,
                 params,
                 ssrData,
-                'event'
+                'event',
+                props || {},
+                exprFns
             );
             if (typeof handler !== 'function') {
                 throwZenithRuntimeError({
@@ -291,11 +331,67 @@ export function hydrate(payload) {
                         });
                     }
                 };
+                if (eventBinding.event === 'esc') {
+                    escDispatchEntries.push({
+                        node,
+                        handler: wrappedHandler
+                    });
+                    continue;
+                }
                 node.addEventListener(eventBinding.event, wrappedHandler);
                 _registerListener(node, eventBinding.event, wrappedHandler);
             }
         }
 
+        if (escDispatchEntries.length > 0) {
+            const doc = root && root.ownerDocument ? root.ownerDocument : (typeof document !== 'undefined' ? document : null);
+            if (doc && typeof doc.addEventListener === 'function') {
+                const escDispatchListener = function zenithEscDispatch(event) {
+                    if (!event || event.key !== 'Escape') {
+                        return;
+                    }
+
+                    const activeElement = doc.activeElement || null;
+                    let targetEntry = null;
+
+                    if (activeElement && activeElement !== doc.body && activeElement !== doc.documentElement) {
+                        for (let i = escDispatchEntries.length - 1; i >= 0; i--) {
+                            const entry = escDispatchEntries[i];
+                            if (!entry || !entry.node) {
+                                continue;
+                            }
+                            if (!entry.node.isConnected) {
+                                continue;
+                            }
+                            if (typeof entry.node.contains === 'function' && entry.node.contains(activeElement)) {
+                                targetEntry = entry;
+                                break;
+                            }
+                        }
+                    }
+
+                    if (!targetEntry && (activeElement === null || activeElement === doc.body || activeElement === doc.documentElement)) {
+                        for (let i = escDispatchEntries.length - 1; i >= 0; i--) {
+                            const entry = escDispatchEntries[i];
+                            if (!entry || !entry.node || !entry.node.isConnected) {
+                                continue;
+                            }
+                            targetEntry = entry;
+                            break;
+                        }
+                    }
+
+                    if (!targetEntry) {
+                        return;
+                    }
+
+                    return targetEntry.handler.call(targetEntry.node, event);
+                };
+                doc.addEventListener('keydown', escDispatchListener);
+                _registerListener(doc, 'keydown', escDispatchListener);
+            }
+        }
+
         return cleanup;
     } catch (error) {
         rethrowZenithRuntimeError(error, {
@@ -336,6 +432,8 @@ function _validatePayload(payload) {
         throw new Error('[Zenith Runtime] hydrate(payload) requires events[]');
     }
 
+    const refs = Array.isArray(payload.refs) ? payload.refs : [];
+
     const stateValues = payload.state_values;
     if (!Array.isArray(stateValues)) {
         throw new Error('[Zenith Runtime] hydrate(payload) requires state_values[]');
@@ -365,6 +463,7 @@ function _validatePayload(payload) {
     const ssrData = payload.ssr_data && typeof payload.ssr_data === 'object'
         ? payload.ssr_data
         : {};
+    const exprFns = Array.isArray(payload.expr_fns) ? payload.expr_fns : [];
 
     if (markers.length !== expressions.length) {
         throw new Error(
@@ -385,6 +484,23 @@ function _validatePayload(payload) {
                 `[Zenith Runtime] expression table out of order at position ${i}: marker_index=${expression.marker_index}`
             );
         }
+        if (expression.fn_index !== undefined && expression.fn_index !== null) {
+            if (!Number.isInteger(expression.fn_index) || expression.fn_index < 0) {
+                throw new Error(`[Zenith Runtime] expression at position ${i} has invalid fn_index`);
+            }
+        }
+        if (expression.signal_indices !== undefined) {
+            if (!Array.isArray(expression.signal_indices)) {
+                throw new Error(`[Zenith Runtime] expression at position ${i} must provide signal_indices[]`);
+            }
+            for (let j = 0; j < expression.signal_indices.length; j++) {
+                if (!Number.isInteger(expression.signal_indices[j]) || expression.signal_indices[j] < 0) {
+                    throw new Error(
+                        `[Zenith Runtime] expression at position ${i} has invalid signal_indices[${j}]`
+                    );
+                }
+            }
+        }
     }
 
     for (let i = 0; i < markers.length; i++) {
@@ -425,6 +541,34 @@ function _validatePayload(payload) {
         }
     }
 
+    for (let i = 0; i < refs.length; i++) {
+        const refBinding = refs[i];
+        if (!refBinding || typeof refBinding !== 'object' || Array.isArray(refBinding)) {
+            throw new Error(`[Zenith Runtime] ref binding at position ${i} must be an object`);
+        }
+        if (!Number.isInteger(refBinding.index) || refBinding.index < 0) {
+            throw new Error(`[Zenith Runtime] ref binding at position ${i} requires non-negative index`);
+        }
+        if (
+            !Number.isInteger(refBinding.state_index) ||
+            refBinding.state_index < 0 ||
+            refBinding.state_index >= stateValues.length
+        ) {
+            throw new Error(
+                `[Zenith Runtime] ref binding at position ${i} has out-of-bounds state_index`
+            );
+        }
+        if (typeof refBinding.selector !== 'string' || refBinding.selector.length === 0) {
+            throw new Error(`[Zenith Runtime] ref binding at position ${i} requires selector`);
+        }
+        const candidate = stateValues[refBinding.state_index];
+        if (!candidate || typeof candidate !== 'object' || !Object.prototype.hasOwnProperty.call(candidate, 'current')) {
+            throw new Error(
+                `[Zenith Runtime] ref binding at position ${i} must resolve to a ref-like object`
+            );
+        }
+    }
+
     for (let i = 0; i < signals.length; i++) {
         const signalDescriptor = signals[i];
         if (!signalDescriptor || typeof signalDescriptor !== 'object' || Array.isArray(signalDescriptor)) {
@@ -478,13 +622,18 @@ function _validatePayload(payload) {
     for (let i = 0; i < expressions.length; i++) Object.freeze(expressions[i]);
     for (let i = 0; i < markers.length; i++) Object.freeze(markers[i]);
     for (let i = 0; i < events.length; i++) Object.freeze(events[i]);
+    for (let i = 0; i < refs.length; i++) Object.freeze(refs[i]);
     for (let i = 0; i < signals.length; i++) Object.freeze(signals[i]);
     for (let i = 0; i < components.length; i++) {
         const c = components[i];
         if (Array.isArray(c.props)) {
             for (let j = 0; j < c.props.length; j++) {
                 const propDesc = c.props[j];
-                if (propDesc && typeof propDesc === 'object' && propDesc.value && typeof propDesc.value === 'object') {
+                if (
+                    propDesc &&
+                    typeof propDesc === 'object' &&
+                    _isHydrationFreezableContainer(propDesc.value)
+                ) {
                     Object.freeze(propDesc.value);
                 }
                 Object.freeze(propDesc);
@@ -497,6 +646,7 @@ function _validatePayload(payload) {
     Object.freeze(expressions);
     Object.freeze(markers);
     Object.freeze(events);
+    Object.freeze(refs);
     Object.freeze(signals);
     Object.freeze(components);
 
@@ -505,6 +655,7 @@ function _validatePayload(payload) {
         expressions,
         markers,
         events,
+        refs,
         stateValues,
         stateKeys,
         signals,
@@ -512,7 +663,8 @@ function _validatePayload(payload) {
         route,
         params: Object.freeze(params),
         ssrData: Object.freeze(ssrData),
-        props: Object.freeze(props)
+        props: Object.freeze(props),
+        exprFns: Object.freeze(exprFns)
     };
 
     return Object.freeze(validatedPayload);
@@ -576,7 +728,34 @@ function _resolveNodes(root, selector, index, kind) {
     return nodes;
 }
 
-function _evaluateExpression(binding, stateValues, stateKeys, signalMap, componentBindings, params, ssrData, mode, props) {
+function _resolveExpressionSignalIndices(binding) {
+    if (!binding || typeof binding !== 'object') {
+        return [];
+    }
+    if (Array.isArray(binding.signal_indices) && binding.signal_indices.length > 0) {
+        return [...new Set(binding.signal_indices.filter((value) => Number.isInteger(value) && value >= 0))];
+    }
+    if (Number.isInteger(binding.signal_index) && binding.signal_index >= 0) {
+        return [binding.signal_index];
+    }
+    return [];
+}
+
+function _evaluateExpression(binding, stateValues, stateKeys, signalMap, componentBindings, params, ssrData, mode, props, exprFns) {
+    if (binding.fn_index != null && binding.fn_index !== undefined) {
+        const fns = Array.isArray(exprFns) ? exprFns : [];
+        const fn = fns[binding.fn_index];
+        if (typeof fn === 'function') {
+            return fn({
+                signalMap,
+                params,
+                ssrData,
+                props: props || {},
+                componentBindings,
+                zenhtml: _zenhtml
+            });
+        }
+    }
     if (binding.signal_index !== null && binding.signal_index !== undefined) {
         const signalValue = signalMap.get(binding.signal_index);
         if (!signalValue || typeof signalValue.get !== 'function') {
@@ -647,17 +826,9 @@ function _evaluateExpression(binding, stateValues, stateKeys, signalMap, compone
                 return props || {};
             }
 
-            const evaluated = _evaluateLiteralExpression(
-                trimmedLiteral,
-                stateValues,
-                stateKeys,
-                params,
-                ssrData,
-                mode,
-                props
-            );
-            if (evaluated !== UNRESOLVED_LITERAL) {
-                return evaluated;
+            const primitiveValue = _resolvePrimitiveLiteral(trimmedLiteral);
+            if (primitiveValue !== UNRESOLVED_LITERAL) {
+                return primitiveValue;
             }
             if (_isLikelyExpressionLiteral(trimmedLiteral)) {
                 throwZenithRuntimeError({
@@ -780,33 +951,39 @@ function _resolveStrictMemberChainLiteral(
     return cursor;
 }
 
-function _evaluateLiteralExpression(expression, stateValues, stateKeys, params, ssrData, mode, props) {
-    const scope = _buildLiteralScope(stateValues, stateKeys, params, ssrData, mode, props);
-    const scopeKeys = Object.keys(scope);
-    const scopeValues = scopeKeys.map((key) => scope[key]);
-    const rewritten = _rewriteMarkupLiterals(expression);
-    const cacheKey = `${scopeKeys.join('|')}::${rewritten}`;
+function _resolvePrimitiveLiteral(literal) {
+    if (typeof literal !== 'string') {
+        return UNRESOLVED_LITERAL;
+    }
+    if (literal === 'true') return true;
+    if (literal === 'false') return false;
+    if (literal === 'null') return null;
+    if (literal === 'undefined') return undefined;
 
-    let evaluator = COMPILED_LITERAL_CACHE.get(cacheKey);
-    if (!evaluator) {
+    if (/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(literal)) {
+        return Number(literal);
+    }
+
+    if (literal.length >= 2 && literal.startsWith('"') && literal.endsWith('"')) {
         try {
-            evaluator = Function(
-                ...scopeKeys,
-                `return (${rewritten});`
-            );
-        } catch (err) {
-            if (isZenithRuntimeError(err)) throw err;
+            return JSON.parse(literal);
+        } catch {
             return UNRESOLVED_LITERAL;
         }
-        COMPILED_LITERAL_CACHE.set(cacheKey, evaluator);
     }
 
-    try {
-        return evaluator(...scopeValues);
-    } catch (err) {
-        if (isZenithRuntimeError(err)) throw err;
-        return UNRESOLVED_LITERAL;
+    if (literal.length >= 2 && literal.startsWith('\'') && literal.endsWith('\'')) {
+        return literal
+            .slice(1, -1)
+            .replace(/\\\\/g, '\\')
+            .replace(/\\'/g, '\'');
+    }
+
+    if (literal.length >= 2 && literal.startsWith('`') && literal.endsWith('`')) {
+        return literal.slice(1, -1);
     }
+
+    return UNRESOLVED_LITERAL;
 }
 
 function _buildLiteralScope(stateValues, stateKeys, params, ssrData, mode, props) {
@@ -1580,10 +1757,7 @@ function _applyAttribute(node, attrName, value) {
 }
 
 function _deepFreezePayload(obj) {
-    if (!obj || typeof obj !== 'object' || Object.isFrozen(obj)) return;
-    // Skip DOM nodes, signals (objects with get/subscribe), and functions
-    if (typeof obj.nodeType === 'number') return;
-    if (typeof obj.get === 'function' && typeof obj.subscribe === 'function') return;
+    if (!_isHydrationFreezableContainer(obj) || Object.isFrozen(obj)) return;
 
     Object.freeze(obj);
     const keys = Object.keys(obj);
@@ -1594,3 +1768,47 @@ function _deepFreezePayload(obj) {
         }
     }
 }
+
+function _isHydrationRefObject(obj) {
+    if (!obj || typeof obj !== 'object') {
+        return false;
+    }
+    if (obj.__zenith_ref === true) {
+        return true;
+    }
+    if (!Object.prototype.hasOwnProperty.call(obj, 'current')) {
+        return false;
+    }
+    if (typeof obj.get === 'function' && typeof obj.subscribe === 'function') {
+        return false;
+    }
+    const keys = Object.keys(obj);
+    if (keys.length === 1 && keys[0] === 'current') {
+        return true;
+    }
+    if (keys.length === 2 && keys.includes('current') && keys.includes('__zenith_ref')) {
+        return true;
+    }
+    return false;
+}
+
+function _isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function _isHydrationFreezableContainer(value) {
+    if (Array.isArray(value)) return true;
+    if (!_isPlainObject(value)) return false;
+
+    if (_isHydrationRefObject(value)) {
+        return false;
+    }
+    if (typeof value.get === 'function' && typeof value.subscribe === 'function') {
+        return false;
+    }
+    return true;
+}

package/dist/index.js

@@ -2,3 +2,5 @@ export { signal } from './signal.js';
 export { state } from './state.js';
 export { zeneffect } from './zeneffect.js';
 export { hydrate } from './hydrate.js';
+export { zenWindow, zenDocument } from './env.js';
+export { zenOn, zenResize, collectRefs } from './platform.js';

package/dist/platform.js

@@ -0,0 +1,102 @@
+// ---------------------------------------------------------------------------
+// platform.js — Zenith Runtime canonical DOM/platform helpers
+// ---------------------------------------------------------------------------
+// zenOn: SSR-safe event subscription with disposer
+// zenResize: window resize handler with rAF throttle
+// collectRefs: deterministic null-filtered ref collection
+// ---------------------------------------------------------------------------
+
+import { zenWindow } from './env.js';
+
+/**
+ * SSR-safe event subscription. Returns disposer.
+ * @param {EventTarget | null} target
+ * @param {string} eventName
+ * @param {EventListener} handler
+ * @param {AddEventListenerOptions | boolean} [options]
+ * @returns {() => void}
+ */
+export function zenOn(target, eventName, handler, options) {
+    if (!target || typeof target.addEventListener !== 'function') {
+        return () => {};
+    }
+    target.addEventListener(eventName, handler, options);
+    return () => {
+        target.removeEventListener(eventName, handler, options);
+    };
+}
+
+/**
+ * Window resize handler with requestAnimationFrame throttle.
+ * Returns disposer.
+ * @param {(size: { w: number; h: number }) => void} handler
+ * @returns {() => void}
+ */
+export function zenResize(handler) {
+    const win = zenWindow();
+    if (!win || typeof win.addEventListener !== 'function') {
+        return () => {};
+    }
+    const hasRaf =
+        typeof win.requestAnimationFrame === 'function'
+        && typeof win.cancelAnimationFrame === 'function';
+    let scheduledId = null;
+    let lastW = Number.NaN;
+    let lastH = Number.NaN;
+
+    const schedule = (callback) => {
+        if (hasRaf) {
+            return win.requestAnimationFrame(callback);
+        }
+        return win.setTimeout(callback, 0);
+    };
+
+    const cancel = (id) => {
+        if (hasRaf) {
+            win.cancelAnimationFrame(id);
+            return;
+        }
+        win.clearTimeout(id);
+    };
+
+    function onResize() {
+        if (scheduledId !== null) return;
+        scheduledId = schedule(() => {
+            scheduledId = null;
+            const w = win.innerWidth;
+            const h = win.innerHeight;
+            if (w !== lastW || h !== lastH) {
+                lastW = w;
+                lastH = h;
+                handler({ w, h });
+            }
+        });
+    }
+
+    win.addEventListener('resize', onResize);
+    onResize();
+
+    return () => {
+        if (scheduledId !== null) {
+            cancel(scheduledId);
+            scheduledId = null;
+        }
+        win.removeEventListener('resize', onResize);
+    };
+}
+
+/**
+ * Deterministic null-filtered collection of ref.current values.
+ * @param {...{ current?: Element | null }} refs
+ * @returns {Element[]}
+ */
+export function collectRefs(...refs) {
+    const out = [];
+    for (let i = 0; i < refs.length; i++) {
+        const node = refs[i] && refs[i].current;
+        if (node && typeof node === 'object' && typeof node.nodeType === 'number') {
+            out.push(node);
+        }
+    }
+    return out;
+}

package/dist/template.js

@@ -22,6 +22,8 @@ function buildRuntimeModuleSource() {
     const segments = [
         stripImports(readRuntimeSourceFile('zeneffect.js')),
         stripImports(readRuntimeSourceFile('ref.js')),
+        stripImports(readRuntimeSourceFile('env.js')),
+        stripImports(readRuntimeSourceFile('platform.js')),
         stripImports(readRuntimeSourceFile('signal.js')),
         stripImports(readRuntimeSourceFile('state.js')),
         stripImports(readRuntimeSourceFile('diagnostics.js')),
@@ -119,18 +121,101 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
       });
   }
 
-  function swapStylesheet(nextHref) {
+  let cssSwapEpoch = 0;
+
+  function withCacheBuster(nextHref) {
+    const separator = nextHref.includes('?') ? '&' : '?';
+    return nextHref + separator + '__zenith_dev=' + Date.now();
+  }
+
+  function isSameOriginStylesheet(href) {
+    if (typeof href !== 'string' || href.length === 0) {
+      return false;
+    }
+    if (href.startsWith('http://') || href.startsWith('https://')) {
+      try {
+        return new URL(href, window.location.href).origin === window.location.origin;
+      } catch {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function findPrimaryStylesheet() {
+    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'))
+      .filter(function (link) {
+        return isSameOriginStylesheet(link.getAttribute('href') || '');
+      });
+    if (links.length === 0) {
+      return null;
+    }
+    const marked = links.find(function (link) {
+      return link.getAttribute('data-zenith-dev-primary') === 'true';
+    });
+    if (marked) {
+      return marked;
+    }
+    links[0].setAttribute('data-zenith-dev-primary', 'true');
+    return links[0];
+  }
+
+  function scheduleCssRetry(previousHref, attempt) {
+    if (attempt >= 3) {
+      window.location.reload();
+      return;
+    }
+    const delayMs = (attempt + 1) * 100;
+    setTimeout(function () {
+      fetchDevState().then(function (statePayload) {
+        const href = statePayload && typeof statePayload.cssHref === 'string' && statePayload.cssHref.length > 0
+          ? statePayload.cssHref
+          : previousHref;
+        swapStylesheet(href, attempt + 1);
+      });
+    }, delayMs);
+  }
+
+  function swapStylesheet(nextHref, attempt) {
+    const tries = Number.isInteger(attempt) ? attempt : 0;
     if (typeof nextHref !== 'string' || nextHref.length === 0) {
       window.location.reload();
       return;
     }
-    const links = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
-    if (links.length === 0) {
+    const activeLink = findPrimaryStylesheet();
+    if (!activeLink) {
       window.location.reload();
       return;
     }
-    const separator = nextHref.includes('?') ? '&' : '?';
-    links[0].setAttribute('href', nextHref + separator + '__zenith_dev=' + Date.now());
+
+    const swapId = ++cssSwapEpoch;
+    const nextLink = activeLink.cloneNode(true);
+    nextLink.setAttribute('href', withCacheBuster(nextHref));
+    nextLink.removeAttribute('data-zenith-dev-primary');
+    nextLink.setAttribute('data-zenith-dev-pending', 'true');
+    activeLink.removeAttribute('data-zenith-dev-primary');
+
+    nextLink.addEventListener('load', function () {
+      if (swapId !== cssSwapEpoch) {
+        try { nextLink.remove(); } catch { }
+        return;
+      }
+      nextLink.removeAttribute('data-zenith-dev-pending');
+      nextLink.setAttribute('data-zenith-dev-primary', 'true');
+      try { activeLink.remove(); } catch { }
+    }, { once: true });
+
+    nextLink.addEventListener('error', function () {
+      if (swapId !== cssSwapEpoch) {
+        try { nextLink.remove(); } catch { }
+        return;
+      }
+      try { nextLink.remove(); } catch { }
+      activeLink.setAttribute('data-zenith-dev-primary', 'true');
+      scheduleCssRetry(nextHref, tries);
+    }, { once: true });
+
+    activeLink.insertAdjacentElement('afterend', nextLink);
   }
 
   const state = ensureDevState();
@@ -341,8 +426,10 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
     appendLog('[css_update] ' + (payload.href || ''));
     emitDebug('css_update', payload);
     fetchDevState().then(function (statePayload) {
-      if (statePayload && typeof statePayload.cssHref === 'string' && statePayload.cssHref.length > 0) {
+      if (statePayload) {
         updateInfo({ ...payload, ...statePayload });
+      }
+      if (statePayload && typeof statePayload.cssHref === 'string' && statePayload.cssHref.length > 0) {
         swapStylesheet(statePayload.cssHref);
         return;
       }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@zenithbuild/runtime",
-  "version": "0.5.0-beta.2.5",
+  "version": "0.6.0",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./template": "./dist/template.js"
   },
   "publishConfig": {
     "access": "public"