@zenithbuild/runtime 0.2.1 → 0.5.0-beta.2.15

package/HYDRATION_CONTRACT.md

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

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

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

package/dist/cleanup.js

@@ -0,0 +1,88 @@
+// ---------------------------------------------------------------------------
+// cleanup.js — Zenith Runtime V0
+// ---------------------------------------------------------------------------
+// Deterministic teardown system.
+//
+// Tracks:
+//   - Active effect disposers
+//   - Active event listeners
+//
+// cleanup() removes everything.
+// Calling cleanup() twice is a no-op.
+// ---------------------------------------------------------------------------
+
+import { resetGlobalSideEffects } from './zeneffect.js';
+
+/** @type {function[]} */
+const _disposers = [];
+
+/** @type {{ element: Element, event: string, handler: function }[]} */
+const _listeners = [];
+
+let _cleaned = false;
+
+/**
+ * Register an effect disposer for later cleanup.
+ *
+ * @param {function} dispose
+ */
+export function _registerDisposer(dispose) {
+    _disposers.push(dispose);
+    _cleaned = false;
+}
+
+/**
+ * Register an event listener for later cleanup.
+ *
+ * @param {Element} element
+ * @param {string} event
+ * @param {function} handler
+ */
+export function _registerListener(element, event, handler) {
+    _listeners.push({ element, event, handler });
+    _cleaned = false;
+}
+
+/**
+ * Tear down all active effects and event listeners.
+ *
+ * - Disposes all effects (clears subscriber sets)
+ * - Removes all event listeners
+ * - Clears registries
+ * - Idempotent: calling twice is a no-op
+ */
+export function cleanup() {
+    // Global zenMount/zenEffect registrations can be created outside hydrate's
+    // disposer table (e.g. page-level component bootstraps). Even when cleanup
+    // has already run once, we still need to reset that scope deterministically.
+    if (_cleaned) {
+        resetGlobalSideEffects();
+        return;
+    }
+
+    // 1. Dispose all effects
+    for (let i = 0; i < _disposers.length; i++) {
+        _disposers[i]();
+    }
+    _disposers.length = 0;
+
+    // 2. Remove all event listeners
+    for (let i = 0; i < _listeners.length; i++) {
+        const { element, event, handler } = _listeners[i];
+        element.removeEventListener(event, handler);
+    }
+    _listeners.length = 0;
+
+    _cleaned = true;
+}
+
+/**
+ * Get counts for testing/debugging.
+ * @returns {{ effects: number, listeners: number }}
+ */
+export function _getCounts() {
+    return {
+        effects: _disposers.length,
+        listeners: _listeners.length
+    };
+}