@zenithbuild/runtime 0.6.13 → 0.6.17

package/dist/diagnostics.js

@@ -2,6 +2,9 @@ const OVERLAY_ID = '__zenith_runtime_error_overlay';
 const MAX_MESSAGE_LENGTH = 120;
 const MAX_HINT_LENGTH = 140;
 const MAX_PATH_LENGTH = 120;
+const MAX_DOCS_LINK_LENGTH = 180;
+const MAX_SNIPPET_LENGTH = 220;
+const MAX_STACK_LENGTH = 420;
 const VALID_PHASES = new Set(['hydrate', 'bind', 'render', 'event']);
 const VALID_CODES = new Set([
     'UNRESOLVED_EXPRESSION',
@@ -9,8 +12,20 @@ const VALID_CODES = new Set([
     'MARKER_MISSING',
     'FRAGMENT_MOUNT_FAILED',
     'BINDING_APPLY_FAILED',
-    'EVENT_HANDLER_FAILED'
+    'EVENT_HANDLER_FAILED',
+    'COMPONENT_BOOTSTRAP_FAILED',
+    'UNSAFE_MEMBER_ACCESS'
 ]);
+const DOCS_LINK_BY_CODE = Object.freeze({
+    UNRESOLVED_EXPRESSION: '/docs/documentation/reference/reactive-binding-model.md#expression-resolution',
+    NON_RENDERABLE_VALUE: '/docs/documentation/reference/reactive-binding-model.md#renderable-values',
+    MARKER_MISSING: '/docs/documentation/reference/markers.md',
+    FRAGMENT_MOUNT_FAILED: '/docs/documentation/contracts/runtime-contract.md#fragment-contract',
+    BINDING_APPLY_FAILED: '/docs/documentation/contracts/runtime-contract.md#binding-application',
+    EVENT_HANDLER_FAILED: '/docs/documentation/contracts/runtime-contract.md#event-bindings',
+    COMPONENT_BOOTSTRAP_FAILED: '/docs/documentation/contracts/runtime-contract.md#component-bootstrap',
+    UNSAFE_MEMBER_ACCESS: '/docs/documentation/reference/reactive-binding-model.md#expression-resolution'
+});
 function _truncate(input, maxLength) {
     const text = String(input ?? '');
     if (text.length <= maxLength)
@@ -48,6 +63,49 @@ function _sanitizePath(value) {
         return undefined;
     return _truncate(compact, MAX_PATH_LENGTH);
 }
+function _sanitizeDocsLink(value) {
+    if (value === null || value === undefined || value === false) {
+        return undefined;
+    }
+    const compact = String(value).replace(/\s+/g, ' ').trim();
+    if (!compact)
+        return undefined;
+    return _truncate(compact, MAX_DOCS_LINK_LENGTH);
+}
+function _sanitizeSourceLocation(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const line = Number(value.line);
+    const column = Number(value.column);
+    if (!Number.isInteger(line) || !Number.isInteger(column)) {
+        return undefined;
+    }
+    if (line < 1 || column < 1) {
+        return undefined;
+    }
+    return { line, column };
+}
+function _sanitizeSource(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const fileRaw = value.file;
+    const file = typeof fileRaw === 'string' ? _truncate(fileRaw.trim(), 240) : '';
+    if (!file) {
+        return undefined;
+    }
+    const start = _sanitizeSourceLocation(value.start);
+    const end = _sanitizeSourceLocation(value.end);
+    const snippet = typeof value.snippet === 'string'
+        ? _truncate(value.snippet.replace(/\s+/g, ' ').trim(), MAX_SNIPPET_LENGTH)
+        : undefined;
+    return {
+        file,
+        ...(start ? { start } : null),
+        ...(end ? { end } : null),
+        ...(snippet ? { snippet } : null)
+    };
+}
 function _normalizeMarker(marker) {
     if (!marker || typeof marker !== 'object')
         return undefined;
@@ -170,9 +228,25 @@ function _renderOverlay(payload) {
     if (payload.path) {
         textLines.push(`path: ${payload.path}`);
     }
+    if (payload.source && payload.source.file) {
+        const line = payload.source.start?.line;
+        const column = payload.source.start?.column;
+        if (Number.isInteger(line) && Number.isInteger(column)) {
+            textLines.push(`source: ${payload.source.file}:${line}:${column}`);
+        }
+        else {
+            textLines.push(`source: ${payload.source.file}`);
+        }
+        if (payload.source.snippet) {
+            textLines.push(`snippet: ${payload.source.snippet}`);
+        }
+    }
     if (payload.hint) {
         textLines.push(`hint: ${payload.hint}`);
     }
+    if (payload.docsLink) {
+        textLines.push(`docs: ${payload.docsLink}`);
+    }
     const jsonText = _safeJson(payload);
     const panelText = textLines.join('\n');
     let pre = overlay.querySelector('pre[data-zx-runtime-error]');
@@ -204,7 +278,9 @@ function _mapLegacyError(error, fallback) {
         message: _sanitizeMessage(fallback.message || safeMessage),
         marker: _normalizeMarker(fallback.marker),
         path: _sanitizePath(fallback.path),
-        hint: _sanitizeHint(fallback.hint)
+        hint: _sanitizeHint(fallback.hint),
+        source: _sanitizeSource(fallback.source),
+        docsLink: _sanitizeDocsLink(fallback.docsLink)
     };
     if (/failed to resolve expression literal/i.test(rawMessage)) {
         details.phase = 'bind';
@@ -232,6 +308,9 @@ function _mapLegacyError(error, fallback) {
         }
         details.hint = details.hint || 'Confirm SSR markers and client selector tables match.';
     }
+    if (!details.docsLink) {
+        details.docsLink = DOCS_LINK_BY_CODE[details.code];
+    }
     return details;
 }
 export function isZenithRuntimeError(error) {
@@ -244,11 +323,13 @@ 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 docsLink = _sanitizeDocsLink(details?.docsLink || DOCS_LINK_BY_CODE[code]);
     const payload = {
         kind: 'ZENITH_RUNTIME_ERROR',
         phase,
         code,
-        message
+        message,
+        ...(docsLink ? { docsLink } : null)
     };
     const marker = _normalizeMarker(details?.marker);
     if (marker)
@@ -259,6 +340,13 @@ export function createZenithRuntimeError(details, cause) {
     const hint = _sanitizeHint(details?.hint);
     if (hint)
         payload.hint = hint;
+    const source = _sanitizeSource(details?.source);
+    if (source)
+        payload.source = source;
+    const stack = _sanitizeHint(details?.stack);
+    if (stack) {
+        payload.stack = _truncate(stack, MAX_STACK_LENGTH);
+    }
     const error = new Error(`[Zenith Runtime] ${code}: ${message}`);
     error.name = 'ZenithRuntimeError';
     error.zenithRuntimeError = payload;
@@ -293,12 +381,18 @@ 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) {
+        const source = !payload.source ? _sanitizeSource(fallback.source) : payload.source;
+        const docsLink = !payload.docsLink
+            ? _sanitizeDocsLink(fallback.docsLink || DOCS_LINK_BY_CODE[payload.code])
+            : payload.docsLink;
+        if (marker || path || hint || source || docsLink) {
             updatedPayload = {
                 ...payload,
                 ...(marker ? { marker } : null),
                 ...(path ? { path } : null),
-                ...(hint ? { hint } : null)
+                ...(hint ? { hint } : null),
+                ...(source ? { source } : null),
+                ...(docsLink ? { docsLink } : null)
             };
             error.zenithRuntimeError = updatedPayload;
             error.toJSON = () => updatedPayload;

package/dist/events.js

@@ -29,10 +29,11 @@ export function bindEvent(element, eventName, exprFn) {
         throwZenithRuntimeError({
             phase: 'bind',
             code: 'BINDING_APPLY_FAILED',
-            message: `Event binding did not resolve to a function for "${eventName}"`,
+            message: `Event binding expected a function reference for "${eventName}"`,
             marker: { type: `data-zx-on-${eventName}`, id: '<unknown>' },
             path: `event:${eventName}`,
-            hint: 'Bind events to function references.'
+            hint: 'Use on:*={handler} and ensure forwarded props are function-valued.',
+            docsLink: '/docs/documentation/contracts/runtime-contract.md#event-bindings'
         });
     }
     const wrapped = function zenithBoundEvent(event) {
@@ -46,7 +47,8 @@ export function bindEvent(element, eventName, exprFn) {
                 message: `Event handler failed for "${eventName}"`,
                 marker: { type: `data-zx-on-${eventName}`, id: '<unknown>' },
                 path: `event:${eventName}:${resolved.name || '<anonymous>'}`,
-                hint: 'Inspect handler logic and referenced state.'
+                hint: 'Inspect handler logic and referenced state.',
+                docsLink: '/docs/documentation/contracts/runtime-contract.md#event-bindings'
             });
         }
     };

package/dist/hydrate.d.ts

@@ -4,14 +4,14 @@
  * @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 }>,
+ *   expressions: Array<{ marker_index: number, signal_index?: number|null, state_index?: number|null, component_instance?: string|null, component_binding?: string|null, literal?: string|null, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>,
+ *   markers: Array<{ index: number, kind: 'text' | 'attr' | 'event', selector: string, attr?: string, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>,
+ *   events: Array<{ index: number, event: string, selector: string, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>,
+ *   refs?: Array<{ index: number, state_index: number, selector: string, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: 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 }>
+ *   components?: Array<{ instance: string, selector: string, create: Function, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>
  * }} payload
  * @returns {() => void}
  */
@@ -25,22 +25,70 @@ export function hydrate(payload: {
         component_instance?: string | null;
         component_binding?: string | null;
         literal?: string | null;
+        source?: {
+            file: string;
+            start?: {
+                line: number;
+                column: number;
+            };
+            end?: {
+                line: number;
+                column: number;
+            };
+            snippet?: string;
+        };
     }>;
     markers: Array<{
         index: number;
         kind: "text" | "attr" | "event";
         selector: string;
         attr?: string;
+        source?: {
+            file: string;
+            start?: {
+                line: number;
+                column: number;
+            };
+            end?: {
+                line: number;
+                column: number;
+            };
+            snippet?: string;
+        };
     }>;
     events: Array<{
         index: number;
         event: string;
         selector: string;
+        source?: {
+            file: string;
+            start?: {
+                line: number;
+                column: number;
+            };
+            end?: {
+                line: number;
+                column: number;
+            };
+            snippet?: string;
+        };
     }>;
     refs?: Array<{
         index: number;
         state_index: number;
         selector: string;
+        source?: {
+            file: string;
+            start?: {
+                line: number;
+                column: number;
+            };
+            end?: {
+                line: number;
+                column: number;
+            };
+            snippet?: string;
+        };
     }>;
     state_values: Array<any>;
     state_keys?: Array<string>;
@@ -53,5 +101,17 @@ export function hydrate(payload: {
         instance: string;
         selector: string;
         create: Function;
+        source?: {
+            file: string;
+            start?: {
+                line: number;
+                column: number;
+            };
+            end?: {
+                line: number;
+                column: number;
+            };
+            snippet?: string;
+        };
     }>;
 }): () => void;

package/dist/hydrate.js

@@ -21,20 +21,27 @@ 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 DOCS_LINKS = Object.freeze({
+    eventBinding: '/docs/documentation/contracts/runtime-contract.md#event-bindings',
+    expressionScope: '/docs/documentation/reference/reactive-binding-model.md#expression-resolution',
+    markerTable: '/docs/documentation/reference/markers.md',
+    componentBootstrap: '/docs/documentation/contracts/runtime-contract.md#component-bootstrap',
+    refs: '/docs/documentation/reference/reactive-binding-model.md#refs-and-mount'
+});
 /**
  * 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 }>,
+ *   expressions: Array<{ marker_index: number, signal_index?: number|null, state_index?: number|null, component_instance?: string|null, component_binding?: string|null, literal?: string|null, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>,
+ *   markers: Array<{ index: number, kind: 'text' | 'attr' | 'event', selector: string, attr?: string, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>,
+ *   events: Array<{ index: number, event: string, selector: string, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>,
+ *   refs?: Array<{ index: number, state_index: number, selector: string, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: 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 }>
+ *   components?: Array<{ instance: string, selector: string, create: Function, source?: { file: string, start?: { line: number, column: number }, end?: { line: number, column: number }, snippet?: string } }>
  * }} payload
  * @returns {() => void}
  */
@@ -61,7 +68,7 @@ export function hydrate(payload) {
         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');
+            const nodes = _resolveNodes(root, refBinding.selector, refBinding.index, 'ref', refBinding.source);
             targetRef.current = nodes[0] || null;
             hydratedRefs.push(targetRef);
         }
@@ -78,38 +85,56 @@ export function hydrate(payload) {
                 component: component.instance,
                 route
             }));
-            const hosts = _resolveNodes(root, component.selector, i, 'component');
+            const hosts = _resolveNodes(root, component.selector, i, 'component', component.source);
             for (let j = 0; j < hosts.length; j++) {
-                const componentScope = createSideEffectScope(`${component.instance}:${j}`);
-                const runtimeApi = {
-                    signal,
-                    state,
-                    zeneffect(effect, dependenciesOrOptions) {
-                        return zeneffect(effect, dependenciesOrOptions, componentScope);
-                    },
-                    zenEffect(effect, options) {
-                        return zenEffect(effect, options, componentScope);
-                    },
-                    zenMount(callback) {
-                        return zenMount(callback, componentScope);
+                try {
+                    const componentScope = createSideEffectScope(`${component.instance}:${j}`);
+                    const runtimeApi = {
+                        signal,
+                        state,
+                        zeneffect(effect, dependenciesOrOptions) {
+                            return zeneffect(effect, dependenciesOrOptions, componentScope);
+                        },
+                        zenEffect(effect, options) {
+                            return zenEffect(effect, options, componentScope);
+                        },
+                        zenMount(callback) {
+                            return zenMount(callback, componentScope);
+                        }
+                    };
+                    const instance = component.create(hosts[j], resolvedProps, runtimeApi);
+                    if (!instance || typeof instance !== 'object') {
+                        throw new Error(`[Zenith Runtime] component factory for ${component.instance} must return an object`);
+                    }
+                    if (typeof instance.mount === 'function') {
+                        instance.mount();
+                    }
+                    activateSideEffectScope(componentScope);
+                    _registerDisposer(() => {
+                        disposeSideEffectScope(componentScope);
+                        if (typeof instance.destroy === 'function') {
+                            instance.destroy();
+                        }
+                    });
+                    if (instance.bindings && typeof instance.bindings === 'object') {
+                        componentBindings[component.instance] = instance.bindings;
                     }
-                };
-                const instance = component.create(hosts[j], resolvedProps, runtimeApi);
-                if (!instance || typeof instance !== 'object') {
-                    throw new Error(`[Zenith Runtime] component factory for ${component.instance} must return an object`);
-                }
-                if (typeof instance.mount === 'function') {
-                    instance.mount();
                 }
-                activateSideEffectScope(componentScope);
-                _registerDisposer(() => {
-                    disposeSideEffectScope(componentScope);
-                    if (typeof instance.destroy === 'function') {
-                        instance.destroy();
+                catch (error) {
+                    try {
+                        rethrowZenithRuntimeError(error, {
+                            phase: 'hydrate',
+                            code: 'COMPONENT_BOOTSTRAP_FAILED',
+                            message: `Component bootstrap failed for "${component.instance}"`,
+                            path: `component[${component.instance}]`,
+                            hint: 'Fix the failing component and refresh; other components continue mounting.',
+                            docsLink: DOCS_LINKS.componentBootstrap,
+                            source: component.source
+                        });
+                    }
+                    catch {
+                        // Fault containment: continue mounting remaining components.
                     }
-                });
-                if (instance.bindings && typeof instance.bindings === 'object') {
-                    componentBindings[component.instance] = instance.bindings;
                 }
             }
         }
@@ -134,9 +159,9 @@ export function hydrate(payload) {
             if (marker.kind === 'event') {
                 continue;
             }
-            const nodes = _resolveNodes(root, marker.selector, marker.index, marker.kind);
+            const nodes = _resolveNodes(root, marker.selector, marker.index, marker.kind, marker.source);
             markerNodesByIndex.set(marker.index, nodes);
-            const value = _evaluateExpression(expressions[marker.index], stateValues, stateKeys, signalMap, componentBindings, params, ssrData, marker.kind, props, exprFns);
+            const value = _evaluateExpression(expressions[marker.index], stateValues, stateKeys, signalMap, componentBindings, params, ssrData, marker.kind, props, exprFns, marker, null);
             _applyMarkerValue(nodes, marker, value);
         }
         for (let i = 0; i < expressions.length; i++) {
@@ -149,9 +174,9 @@ export function hydrate(payload) {
             if (!marker || marker.kind === 'event') {
                 return;
             }
-            const nodes = markerNodesByIndex.get(index) || _resolveNodes(root, marker.selector, marker.index, marker.kind);
+            const nodes = markerNodesByIndex.get(index) || _resolveNodes(root, marker.selector, marker.index, marker.kind, marker.source);
             markerNodesByIndex.set(index, nodes);
-            const value = _evaluateExpression(expressions[index], stateValues, stateKeys, signalMap, componentBindings, params, ssrData, marker.kind, props, exprFns);
+            const value = _evaluateExpression(expressions[index], stateValues, stateKeys, signalMap, componentBindings, params, ssrData, marker.kind, props, exprFns, marker, null);
             _applyMarkerValue(nodes, marker, value);
         }
         const dependentMarkersBySignal = new Map();
@@ -225,16 +250,21 @@ export function hydrate(payload) {
                 throw new Error(`[Zenith Runtime] duplicate event index ${eventBinding.index}`);
             }
             eventIndices.add(eventBinding.index);
-            const nodes = _resolveNodes(root, eventBinding.selector, eventBinding.index, 'event');
-            const handler = _evaluateExpression(expressions[eventBinding.index], stateValues, stateKeys, signalMap, componentBindings, params, ssrData, 'event', props || {}, exprFns);
+            const marker = markerByIndex.get(eventBinding.index) || null;
+            const nodes = _resolveNodes(root, eventBinding.selector, eventBinding.index, 'event', eventBinding.source || marker?.source);
+            const expressionBinding = expressions[eventBinding.index];
+            const handler = _evaluateExpression(expressionBinding, stateValues, stateKeys, signalMap, componentBindings, params, ssrData, 'event', props || {}, exprFns, marker, eventBinding);
             if (typeof handler !== 'function') {
+                const passedExpression = _describeBindingExpression(expressionBinding);
                 throwZenithRuntimeError({
                     phase: 'bind',
                     code: 'BINDING_APPLY_FAILED',
-                    message: `Event binding at index ${eventBinding.index} did not resolve to a function`,
+                    message: `Event binding at index ${eventBinding.index} expected a function reference. You passed: ${passedExpression}`,
                     marker: { type: `data-zx-on-${eventBinding.event}`, id: eventBinding.index },
                     path: `event[${eventBinding.index}].${eventBinding.event}`,
-                    hint: 'Bind events to function references (on:click={handler}).'
+                    hint: 'Use on:*={handler} or ensure the forwarded prop is a function.',
+                    docsLink: DOCS_LINKS.eventBinding,
+                    source: _resolveBindingSource(expressionBinding, marker, eventBinding)
                 });
             }
             for (let j = 0; j < nodes.length; j++) {
@@ -250,7 +280,9 @@ export function hydrate(payload) {
                             message: `Event handler failed for "${eventBinding.event}"`,
                             marker: { type: `data-zx-on-${eventBinding.event}`, id: eventBinding.index },
                             path: `event[${eventBinding.index}].${eventBinding.event}`,
-                            hint: 'Inspect the handler body and referenced state.'
+                            hint: 'Inspect the handler body and referenced state.',
+                            docsLink: DOCS_LINKS.eventBinding,
+                            source: _resolveBindingSource(expressionBinding, marker, eventBinding)
                         });
                     }
                 };
@@ -314,7 +346,8 @@ export function hydrate(payload) {
         rethrowZenithRuntimeError(error, {
             phase: 'hydrate',
             code: 'BINDING_APPLY_FAILED',
-            hint: 'Inspect marker tables, expression bindings, and the runtime overlay diagnostics.'
+            hint: 'Inspect marker tables, expression bindings, and the runtime overlay diagnostics.',
+            docsLink: DOCS_LINKS.markerTable
         });
     }
 }
@@ -390,6 +423,7 @@ function _validatePayload(payload) {
                 throw new Error(`[Zenith Runtime] expression at position ${i} has invalid fn_index`);
             }
         }
+        _assertValidSourceSpan(expression.source, `expression[${i}]`);
         if (expression.signal_indices !== undefined) {
             if (!Array.isArray(expression.signal_indices)) {
                 throw new Error(`[Zenith Runtime] expression at position ${i} must provide signal_indices[]`);
@@ -421,6 +455,7 @@ function _validatePayload(payload) {
         if (marker.kind === 'attr' && (typeof marker.attr !== 'string' || marker.attr.length === 0)) {
             throw new Error(`[Zenith Runtime] attr marker at position ${i} requires attr name`);
         }
+        _assertValidSourceSpan(marker.source, `marker[${i}]`);
     }
     for (let i = 0; i < events.length; i++) {
         const eventBinding = events[i];
@@ -436,6 +471,7 @@ function _validatePayload(payload) {
         if (typeof eventBinding.selector !== 'string' || eventBinding.selector.length === 0) {
             throw new Error(`[Zenith Runtime] event binding at position ${i} requires selector`);
         }
+        _assertValidSourceSpan(eventBinding.source, `event[${i}]`);
     }
     for (let i = 0; i < refs.length; i++) {
         const refBinding = refs[i];
@@ -453,6 +489,7 @@ function _validatePayload(payload) {
         if (typeof refBinding.selector !== 'string' || refBinding.selector.length === 0) {
             throw new Error(`[Zenith Runtime] ref binding at position ${i} requires selector`);
         }
+        _assertValidSourceSpan(refBinding.source, `ref[${i}]`);
         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`);
@@ -490,6 +527,7 @@ function _validatePayload(payload) {
         if (typeof component.create !== 'function') {
             throw new Error(`[Zenith Runtime] component at position ${i} requires create() function`);
         }
+        _assertValidSourceSpan(component.source, `component[${i}]`);
     }
     if (payload.params !== undefined) {
         if (!payload.params || typeof payload.params !== 'object' || Array.isArray(payload.params)) {
@@ -554,6 +592,36 @@ function _validatePayload(payload) {
     };
     return Object.freeze(validatedPayload);
 }
+function _assertValidSourceSpan(source, contextLabel) {
+    if (source === undefined || source === null) {
+        return;
+    }
+    if (!source || typeof source !== 'object' || Array.isArray(source)) {
+        throw new Error(`[Zenith Runtime] ${contextLabel}.source must be an object`);
+    }
+    if (typeof source.file !== 'string' || source.file.length === 0) {
+        throw new Error(`[Zenith Runtime] ${contextLabel}.source.file must be a non-empty string`);
+    }
+    const points = ['start', 'end'];
+    for (let i = 0; i < points.length; i++) {
+        const point = source[points[i]];
+        if (point === undefined || point === null) {
+            continue;
+        }
+        if (!point || typeof point !== 'object' || Array.isArray(point)) {
+            throw new Error(`[Zenith Runtime] ${contextLabel}.source.${points[i]} must be an object`);
+        }
+        if (!Number.isInteger(point.line) || point.line < 1) {
+            throw new Error(`[Zenith Runtime] ${contextLabel}.source.${points[i]}.line must be >= 1`);
+        }
+        if (!Number.isInteger(point.column) || point.column < 1) {
+            throw new Error(`[Zenith Runtime] ${contextLabel}.source.${points[i]}.column must be >= 1`);
+        }
+    }
+    if (source.snippet !== undefined && source.snippet !== null && typeof source.snippet !== 'string') {
+        throw new Error(`[Zenith Runtime] ${contextLabel}.source.snippet must be a string when provided`);
+    }
+}
 function _resolveComponentProps(propTable, signalMap, context = {}) {
     if (!Array.isArray(propTable)) {
         throw new Error('[Zenith Runtime] component props must be an array');
@@ -592,16 +660,21 @@ function _resolveComponentProps(propTable, signalMap, context = {}) {
     }
     return resolved;
 }
-function _resolveNodes(root, selector, index, kind) {
+function _resolveNodes(root, selector, index, kind, source = undefined) {
     const nodes = root.querySelectorAll(selector);
     if (!nodes || nodes.length === 0) {
+        const isRef = kind === 'ref';
         throwZenithRuntimeError({
             phase: 'bind',
             code: 'MARKER_MISSING',
             message: `Unresolved ${kind} marker index ${index}`,
             marker: { type: kind, id: index },
             path: `selector:${selector}`,
-            hint: 'Confirm SSR marker attributes and runtime selector tables match.'
+            hint: isRef
+                ? 'Use ref + zenMount and ensure the ref is bound in markup before mount.'
+                : 'Confirm SSR marker attributes and runtime selector tables match.',
+            docsLink: isRef ? DOCS_LINKS.refs : DOCS_LINKS.markerTable,
+            source
         });
     }
     return nodes;
@@ -618,7 +691,7 @@ function _resolveExpressionSignalIndices(binding) {
     }
     return [];
 }
-function _evaluateExpression(binding, stateValues, stateKeys, signalMap, componentBindings, params, ssrData, mode, props, exprFns) {
+function _evaluateExpression(binding, stateValues, stateKeys, signalMap, componentBindings, params, ssrData, mode, props, exprFns, markerBinding = null, eventBinding = null) {
     if (binding.fn_index != null && binding.fn_index !== undefined) {
         const fns = Array.isArray(exprFns) ? exprFns : [];
         const fn = fns[binding.fn_index];
@@ -678,7 +751,7 @@ function _evaluateExpression(binding, stateValues, stateKeys, signalMap, compone
     if (binding.literal !== null && binding.literal !== undefined) {
         if (typeof binding.literal === 'string') {
             const trimmedLiteral = binding.literal.trim();
-            const strictMemberValue = _resolveStrictMemberChainLiteral(trimmedLiteral, stateValues, stateKeys, params, ssrData, mode, props, binding.marker_index);
+            const strictMemberValue = _resolveStrictMemberChainLiteral(trimmedLiteral, stateValues, stateKeys, params, ssrData, mode, props, binding.marker_index, _resolveBindingSource(binding, markerBinding, eventBinding));
             if (strictMemberValue !== UNRESOLVED_LITERAL) {
                 return strictMemberValue;
             }
@@ -696,16 +769,23 @@ function _evaluateExpression(binding, stateValues, stateKeys, signalMap, compone
                 return primitiveValue;
             }
             if (_isLikelyExpressionLiteral(trimmedLiteral)) {
+                const missingIdentifier = _extractMissingIdentifier(trimmedLiteral);
                 throwZenithRuntimeError({
                     phase: 'bind',
                     code: 'UNRESOLVED_EXPRESSION',
-                    message: `Failed to resolve expression literal: ${_truncateLiteralForError(trimmedLiteral)}`,
+                    message: missingIdentifier
+                        ? `Unresolved expression identifier "${missingIdentifier}" in ${_truncateLiteralForError(trimmedLiteral)}`
+                        : `Failed to resolve expression literal: ${_truncateLiteralForError(trimmedLiteral)}`,
                     marker: {
                         type: _markerTypeForError(mode),
                         id: binding.marker_index
                     },
                     path: `expression[${binding.marker_index}]`,
-                    hint: 'Ensure the expression references declared state keys or params/data bindings.'
+                    hint: missingIdentifier
+                        ? `Declare "${missingIdentifier}" in scope or pass it via props.`
+                        : 'Declare the missing identifier in scope or pass it via props.',
+                    docsLink: DOCS_LINKS.expressionScope,
+                    source: _resolveBindingSource(binding, markerBinding, eventBinding)
                 });
             }
         }
@@ -713,7 +793,7 @@ function _evaluateExpression(binding, stateValues, stateKeys, signalMap, compone
     }
     return '';
 }
-function _throwUnresolvedMemberChainError(literal, markerIndex, mode, pathSuffix, hint) {
+function _throwUnresolvedMemberChainError(literal, markerIndex, mode, pathSuffix, hint, source) {
     throwZenithRuntimeError({
         phase: 'bind',
         code: 'UNRESOLVED_EXPRESSION',
@@ -723,10 +803,12 @@ function _throwUnresolvedMemberChainError(literal, markerIndex, mode, pathSuffix
             id: markerIndex
         },
         path: `marker[${markerIndex}].${pathSuffix}`,
-        hint
+        hint,
+        docsLink: DOCS_LINKS.expressionScope,
+        source
     });
 }
-function _resolveStrictMemberChainLiteral(literal, stateValues, stateKeys, params, ssrData, mode, props, markerIndex) {
+function _resolveStrictMemberChainLiteral(literal, stateValues, stateKeys, params, ssrData, mode, props, markerIndex, source) {
     if (typeof literal !== 'string' || !STRICT_MEMBER_CHAIN_LITERAL_RE.test(literal)) {
         return UNRESOLVED_LITERAL;
     }
@@ -742,7 +824,7 @@ function _resolveStrictMemberChainLiteral(literal, stateValues, stateKeys, param
     const baseIdentifier = segments[0];
     const scope = _buildLiteralScope(stateValues, stateKeys, params, ssrData, mode, props);
     if (!Object.prototype.hasOwnProperty.call(scope, baseIdentifier)) {
-        _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${baseIdentifier}`, `Base identifier "${baseIdentifier}" is not bound. Check props/data/params and declared state keys.`);
+        _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${baseIdentifier}`, `Base identifier "${baseIdentifier}" is not bound. Check props/data/params and declared state keys.`, source);
     }
     let cursor = scope[baseIdentifier];
     let traversedPath = baseIdentifier;
@@ -754,18 +836,20 @@ function _resolveStrictMemberChainLiteral(literal, stateValues, stateKeys, param
                 code: 'UNSAFE_MEMBER_ACCESS',
                 message: `Blocked unsafe member access: ${segment} in path "${literal}"`,
                 path: `marker[${markerIndex}].expression.${literal}`,
-                hint: 'Property access to __proto__, prototype, and constructor is forbidden.'
+                hint: 'Property access to __proto__, prototype, and constructor is forbidden.',
+                docsLink: DOCS_LINKS.expressionScope,
+                source
             });
         }
         if (cursor === null || cursor === undefined) {
-            _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${traversedPath}.${segment}`, `Cannot read "${segment}" from ${traversedPath} because it is null or undefined.`);
+            _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${traversedPath}.${segment}`, `Cannot read "${segment}" from ${traversedPath} because it is null or undefined.`, source);
         }
         const cursorType = typeof cursor;
         if (cursorType !== 'object' && cursorType !== 'function') {
-            _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${traversedPath}.${segment}`, `Cannot read "${segment}" from ${traversedPath} because it resolved to a ${cursorType}.`);
+            _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${traversedPath}.${segment}`, `Cannot read "${segment}" from ${traversedPath} because it resolved to a ${cursorType}.`, source);
         }
         if (!Object.prototype.hasOwnProperty.call(cursor, segment)) {
-            _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${traversedPath}.${segment}`, `Missing member "${segment}" on ${traversedPath}. Check your bindings.`);
+            _throwUnresolvedMemberChainError(literal, markerIndex, mode, `expression.${traversedPath}.${segment}`, `Missing member "${segment}" on ${traversedPath}. Check your bindings.`, source);
         }
         cursor = cursor[segment];
         traversedPath = `${traversedPath}.${segment}`;
@@ -898,6 +982,52 @@ function _isLikelyExpressionLiteral(literal) {
     }
     return /=>|[()[\]{}<>=?:.+\-*/%|&!]/.test(trimmed);
 }
+function _extractMissingIdentifier(literal) {
+    if (typeof literal !== 'string') {
+        return null;
+    }
+    const match = literal.trim().match(/^([A-Za-z_$][A-Za-z0-9_$]*)/);
+    if (!match) {
+        return null;
+    }
+    const candidate = match[1];
+    if (candidate === 'true' || candidate === 'false' || candidate === 'null' || candidate === 'undefined') {
+        return null;
+    }
+    return candidate;
+}
+function _resolveBindingSource(binding, markerBinding, eventBinding) {
+    const candidates = [
+        binding?.source,
+        eventBinding?.source,
+        markerBinding?.source
+    ];
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        if (candidate && typeof candidate === 'object' && typeof candidate.file === 'string') {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function _describeBindingExpression(binding) {
+    if (!binding || typeof binding !== 'object') {
+        return '<unknown>';
+    }
+    if (typeof binding.literal === 'string' && binding.literal.trim().length > 0) {
+        return _truncateLiteralForError(binding.literal.trim());
+    }
+    if (Number.isInteger(binding.state_index)) {
+        return `state[${binding.state_index}]`;
+    }
+    if (Number.isInteger(binding.signal_index)) {
+        return `signal[${binding.signal_index}]`;
+    }
+    if (typeof binding.component_instance === 'string' && typeof binding.component_binding === 'string') {
+        return `${binding.component_instance}.${binding.component_binding}`;
+    }
+    return '<unknown expression>';
+}
 function _markerTypeForError(kind) {
     if (kind === 'text')
         return 'data-zx-e';
@@ -1337,7 +1467,9 @@ function _applyMarkerValue(nodes, marker, value) {
                 path: marker.kind === 'attr'
                     ? `${markerPath}.attr.${marker.attr}`
                     : `${markerPath}.${marker.kind}`,
-                hint: 'Check the binding value type and marker mapping.'
+                hint: 'Check the binding value type and marker mapping.',
+                docsLink: DOCS_LINKS.markerTable,
+                source: marker.source
             });
         }
     }
@@ -1396,7 +1528,8 @@ function _mountStructuralFragment(container, value, rootPath = 'renderable') {
             code: 'FRAGMENT_MOUNT_FAILED',
             message: 'Fragment mount failed',
             path: rootPath,
-            hint: 'Verify fragment values and nested renderable arrays.'
+            hint: 'Verify fragment values and nested renderable arrays.',
+            docsLink: DOCS_LINKS.markerTable
         });
     }
     container.__z_unmounts = newUnmounts;
@@ -1410,7 +1543,8 @@ function _coerceText(value, path = 'renderable') {
             code: 'NON_RENDERABLE_VALUE',
             message: `Zenith Render Error: non-renderable function at ${path}. Use map() to render fields.`,
             path,
-            hint: 'Convert functions into explicit event handlers or renderable text.'
+            hint: 'Convert functions into explicit event handlers or renderable text.',
+            docsLink: DOCS_LINKS.expressionScope
         });
     }
     if (value && typeof value === 'object') {
@@ -1419,7 +1553,8 @@ function _coerceText(value, path = 'renderable') {
             code: 'NON_RENDERABLE_VALUE',
             message: `Zenith Render Error: non-renderable object at ${path}. Use map() to render fields.`,
             path,
-            hint: 'Use map() to render object fields into nodes.'
+            hint: 'Use map() to render object fields into nodes.',
+            docsLink: DOCS_LINKS.expressionScope
         });
     }
     return String(value);

package/dist/template.js

@@ -113,6 +113,8 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
   }
 
   let cssSwapEpoch = 0;
+  const CSS_UPDATE_DOCS = '/docs/documentation/contracts/hmr-v1-contract.md#css-updates';
+  const BUILD_ERROR_DOCS = '/docs/documentation/contracts/runtime-contract.md#diagnostics';
 
   function withCacheBuster(nextHref) {
     const separator = nextHref.includes('?') ? '&' : '?';
@@ -153,7 +155,7 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
 
   function scheduleCssRetry(previousHref, attempt) {
     if (attempt >= 3) {
-      window.location.reload();
+      reportBuildFailure('CSS update failed (404): server build not ready', CSS_UPDATE_DOCS);
       return;
     }
     const delayMs = (attempt + 1) * 100;
@@ -220,6 +222,19 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
   shell.style.fontSize = '12px';
   shell.style.pointerEvents = 'none';
 
+  const buildFailure = document.createElement('div');
+  buildFailure.setAttribute('data-zenith-dev-build-error', 'true');
+  buildFailure.style.display = 'none';
+  buildFailure.style.marginBottom = '8px';
+  buildFailure.style.padding = '8px 10px';
+  buildFailure.style.maxWidth = '420px';
+  buildFailure.style.pointerEvents = 'auto';
+  buildFailure.style.border = '1px solid rgba(255,106,106,0.8)';
+  buildFailure.style.borderRadius = '8px';
+  buildFailure.style.background = 'rgba(90, 16, 16, 0.92)';
+  buildFailure.style.color = '#ffe8e8';
+  buildFailure.style.whiteSpace = 'pre-wrap';
+
   const pill = document.createElement('button');
   pill.type = 'button';
   pill.textContent = 'Zenith Dev';
@@ -243,6 +258,29 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
   panel.style.borderRadius = '10px';
   panel.style.padding = '10px';
   panel.style.boxShadow = '0 14px 30px rgba(0,0,0,0.35)';
+  let lastBuildFailureSignature = '';
+
+  function reportBuildFailure(message, docsLink) {
+    const normalizedMessage = typeof message === 'string' && message.trim().length > 0
+      ? message.trim()
+      : 'Build failed - fix errors to continue.';
+    const signature = normalizedMessage + '|' + String(docsLink || '');
+    if (signature !== lastBuildFailureSignature) {
+      appendLog('[build_failed] ' + normalizedMessage);
+      lastBuildFailureSignature = signature;
+    }
+    const docsText = typeof docsLink === 'string' && docsLink.length > 0
+      ? '\\nDocs: ' + docsLink
+      : '';
+    buildFailure.textContent = 'Build failed - fix errors to continue\\n' + normalizedMessage + docsText;
+    buildFailure.style.display = 'block';
+  }
+
+  function clearBuildFailure() {
+    lastBuildFailureSignature = '';
+    buildFailure.style.display = 'none';
+    buildFailure.textContent = '';
+  }
 
   const status = document.createElement('div');
   status.textContent = 'status: connecting';
@@ -292,7 +330,7 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
   logs.textContent = '[zenith-dev] waiting for server events...';
 
   panel.append(status, info, controls, logs);
-  shell.append(pill, panel);
+  shell.append(buildFailure, pill, panel);
 
   function setOpen(open) {
     state.overlay.open = open === true;
@@ -313,6 +351,9 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
     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';
+    const errorMessage = payload && payload.error && typeof payload.error.message === 'string'
+      ? payload.error.message
+      : (typeof payload.message === 'string' ? payload.message : '');
     info.textContent =
       'server: ' + serverUrl + '\\n' +
       'route: ' + route + '\\n' +
@@ -321,6 +362,11 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
       'hash: ' + hash + '\\n' +
       'duration: ' + duration + '\\n' +
       'changed: ' + changed;
+    if (buildStatus === 'error') {
+      reportBuildFailure(errorMessage || 'Dev build is in an error state.', BUILD_ERROR_DOCS);
+    } else if (buildStatus === 'ok' || buildStatus === 'building') {
+      clearBuildFailure();
+    }
   }
 
   function allLogsEnabled() {
@@ -388,12 +434,14 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
   source.addEventListener('build_start', function (event) {
     const payload = parseEventData(event.data);
     status.textContent = 'status: rebuilding';
+    clearBuildFailure();
     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';
+    clearBuildFailure();
     updateInfo(payload);
     appendLog('[build_complete] ' + (Number.isFinite(payload.durationMs) ? payload.durationMs + 'ms' : 'done'));
     emitDebug('build_complete', payload);
@@ -401,6 +449,8 @@ const RUNTIME_DEV_CLIENT_SOURCE = `(() => {
   source.addEventListener('build_error', function (event) {
     const payload = parseEventData(event.data);
     status.textContent = 'status: error';
+    reportBuildFailure(payload.message || 'Build failed', BUILD_ERROR_DOCS);
+    updateInfo(payload);
     appendLog('[build_error] ' + (payload.message || 'Unknown error'));
     emitDebug('build_error', payload);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/runtime",
-  "version": "0.6.13",
+  "version": "0.6.17",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {