dalila 1.1.1 → 1.3.0

package/README.md

@@ -10,21 +10,22 @@ Dalila is a **SPA**, **DOM-first**, **HTML natural** framework based on **signal
 - 🚀 **Signals-based reactivity** - Automatic dependency tracking
 - 🎯 **DOM-first rendering** - Direct DOM manipulation, no Virtual DOM
 - 🔄 **Scope-based lifecycle** - Automatic cleanup (best effort)
+- 🧿 **DOM lifecycle watchers** — `watch()` + helpers (`useEvent`, `useInterval`, `useTimeout`, `useFetch`) with scope-based cleanup
 - 🛣️ **SPA router** - Basic routing with loaders and AbortSignal
 - 📦 **Context system** - Reactive dependency injection
 - 🔧 **Scheduler & batching** - Group updates into a single frame
-- 📚 **List rendering** - `createList` for keyed lists
+- 📚 **List rendering** - `createList` with keyed diffing for efficient updates
 - 🧱 **Resources** - Async data helpers with AbortSignal and scope cleanup
 
 ### Experimental
 - 🎨 **Natural HTML bindings** - Only in the example dev-server (not in core)
-- 📊 **Virtualization** - Virtual lists/tables are experimental
 - 🔍 **DevTools (console)** - Warnings and FPS monitor only
-- 🧪 **Low-level list API** - `forEach` (experimental, prefer `createList`)
+- 🧪 **Low-level list API** - `forEach` (advanced control, use when you need fine-grained behavior like reactive index; `createList` is the default)
 
 ### Planned / Roadmap
 - 🧰 **DevTools UI** - Visual inspection tooling
 - 🧩 **HTML bindings runtime/compiler** - First-class template binding
+- 📊 **Virtualization** - Virtual lists/tables for very large datasets (10k+ items)
 
 ## 📦 Installation
 
@@ -54,7 +55,7 @@ export function createController() {
 }
 ```
 
-> Note: HTML bindings in this example are provided by the example dev-server,
+> Note: HTML bindings in this example are provided by the example dev-server (`npm run serve`),
 > not by the core runtime.
 
 ## 🧪 Local Demo Server
@@ -95,6 +96,80 @@ effectAsync(async (signal) => {
 });
 ```
 
+### Lifecycle / Cleanup (Scopes + DOM)
+
+Dalila is DOM-first. That means a lot of your "lifecycle" work is not React-like rendering —
+it's **attaching listeners, timers, and async work to real DOM nodes**.
+
+Dalila's rule is simple:
+
+- **Inside a scope** → cleanup is automatic (best-effort) on `scope.dispose()`
+- **Outside a scope** → you must call `dispose()` manually unless a primitive explicitly auto-disposes on DOM removal (Dalila warns in dev mode)
+
+#### `watch(node, fn)` — DOM lifecycle primitive
+
+`watch()` runs a reactive function while a DOM node is connected.
+When the node disconnects, the effect is disposed. If the node reconnects later, it starts again.
+It's the primitive that enables DOM lifecycle without a VDOM.
+
+```ts
+import { watch, signal } from "dalila";
+
+const count = signal(0);
+
+const dispose = watch(someNode, () => {
+  // Reactive while connected because watch() runs this inside an effect()
+  someNode.textContent = String(count());
+});
+
+// later (optional if inside a scope)
+dispose();
+```
+
+#### Lifecycle helpers
+
+Built on the same mental model, Dalila provides small helpers that always return an **idempotent** `dispose()`:
+`useEvent`, `useInterval`, `useTimeout`, `useFetch`.
+
+**Inside a scope (recommended)**
+
+```ts
+import { createScope, withScope, useEvent, useInterval, useFetch } from "dalila";
+
+const scope = createScope();
+
+withScope(scope, () => {
+  useEvent(button, "click", onClick);
+  useInterval(tick, 1000);
+
+  const user = useFetch("/api/user");
+
+  // Optional manual cleanup:
+  // user.dispose();
+});
+
+scope.dispose(); // stops listener, interval, and aborts fetch
+```
+
+Disposing the scope stops listeners/timers and aborts in-flight async work created inside the scope.
+
+**Outside a scope (manual cleanup)**
+
+```ts
+import { useInterval } from "dalila";
+
+const dispose = useInterval(() => console.log("tick"), 1000);
+
+// later...
+dispose(); // required
+```
+
+#### Why helpers vs native APIs?
+
+You *can* use `addEventListener` / `setTimeout` / `setInterval` directly, but then cleanup becomes "manual discipline".
+In a DOM-first app, listeners/timers are the #1 source of silent leaks when the UI changes.
+Scopes make cleanup a **default**, not a convention — so UI changes don't silently leak listeners, timers, or in-flight async work.
+
 ### Conditional Rendering
 
 Dalila provides two primitives for branching UI:
@@ -223,18 +298,61 @@ mutate(() => {
 - This allows reading updated values inside the batch while coalescing UI updates
 
 ### List Rendering with Keys
+
+Dalila provides efficient list rendering with keyed diffing, similar to React's `key` prop or Vue's `:key`.
+
+**Basic usage:**
 ```typescript
-// Primary API (stable)
-createList(
-  todos,
-  (todo) => div(todo.text)
+import { signal } from 'dalila';
+import { createList } from 'dalila/core';
+
+const todos = signal([
+  { id: 1, text: 'Learn Dalila', done: true },
+  { id: 2, text: 'Build app', done: false }
+]);
+
+const listFragment = createList(
+  () => todos(),
+  (todo) => {
+    const li = document.createElement('li');
+    li.textContent = todo.text;
+    return li;
+  },
+  (todo) => todo.id.toString() // Key function
 );
 
-// Experimental low-level API
-forEach(
-  items,
-  (item) => div(item.name),
-  (item) => item.id // Key function
+document.body.append(listFragment);
+```
+
+**Key function best practices:**
+- ✅ Always provide a keyFn for dynamic lists
+- ✅ Use stable, unique identifiers (IDs, not indices)
+- ✅ Avoid using object references as keys
+- ⚠️ Without keyFn, items use index as key (re-renders on reorder)
+
+**How it works:**
+- Only re-renders items whose value changed (not items that only moved)
+- Preserves DOM nodes for unchanged items (maintains focus, scroll, etc)
+- Efficient for lists up to ~1000 items (informal guideline, not yet benchmarked)
+- Each item gets its own scope for automatic cleanup
+- Outside a scope, the list auto-disposes when removed from the DOM (or call `fragment.dispose()`)
+> **Note:** In `createList`, `index` is a snapshot (not reactive). Reorder moves nodes without re-render. Use `forEach()` if you need a reactive index.
+
+**Performance:**
+```typescript
+// Bad: re-creates all items on every change
+effect(() => {
+  container.innerHTML = '';
+  todos().forEach(todo => {
+    container.append(createTodoItem(todo));
+  });
+});
+
+// Good: only updates changed items
+const list = createList(
+  () => todos(),
+  (todo) => createTodoItem(todo),
+  (todo) => todo.id.toString()
 );
 ```
 
@@ -521,7 +639,7 @@ Dalila is built around these core principles:
 | Rendering | Virtual DOM diffing | Direct DOM manipulation |
 | Performance | Manual optimization | Runtime scheduling (best-effort) |
 | State management | Hooks + deps arrays | Signals + automatic tracking |
-| Side effects | `useEffect` + deps | `effect()` + automatic cleanup |
+| Side effects | `useEffect` + deps | `effect()` + automatic cleanup (best-effort) |
 | Bundle size | ~40KB | Not yet measured |
 
 ## 📁 Project Structure

package/dist/core/dev.d.ts

@@ -1,23 +1,2 @@
 export declare function setDevMode(enabled: boolean): void;
 export declare function isInDevMode(): boolean;
-export declare function warnIfAsyncEffectWithoutAbort(): void;
-export declare function warnIfLayoutReadInMutate(): void;
-export declare function warnIfSignalUsedOutsideScope(): void;
-export declare function checkLayoutThrashing(): Promise<void>;
-export declare function monitorPerformance(): void;
-export declare function detectMemoryLeaks(): void;
-export declare function initDevTools(): Promise<void>;
-export declare function inspectSignal<T>(signal: () => T): {
-    value: T;
-    subscribers: number;
-};
-export declare function trackEffect(fn: Function): () => void;
-export declare function getActiveEffects(): Array<{
-    id: number;
-    fn: Function;
-    stack: string;
-}>;
-export declare function getCurrentScopeInfo(): {
-    cleanupCount: number;
-    effectCount: number;
-};

package/dist/core/dev.js

@@ -1,5 +1,4 @@
-import { getCurrentScope } from './scope.js';
-import { measure, mutate } from './scheduler.js';
+// dev.ts
 let isDevMode = true;
 export function setDevMode(enabled) {
     isDevMode = enabled;
@@ -7,151 +6,3 @@ export function setDevMode(enabled) {
 export function isInDevMode() {
     return isDevMode;
 }
-// Dev warnings for common performance issues
-export function warnIfAsyncEffectWithoutAbort() {
-    if (!isDevMode)
-        return;
-    console.warn('⚠️ Async effect without AbortSignal: ' +
-        'This may cause race conditions. Use effectAsync with signal parameter instead.');
-}
-export function warnIfLayoutReadInMutate() {
-    if (!isDevMode)
-        return;
-    console.warn('⚠️ Layout read in mutate phase: ' +
-        'This may cause forced reflows. Use measure() for reads and mutate() for writes.');
-}
-export function warnIfSignalUsedOutsideScope() {
-    if (!isDevMode)
-        return;
-    console.warn('⚠️ Signal used outside scope: ' +
-        'Signals should be created and used within a scope for proper cleanup.');
-}
-// Check for layout thrashing
-export async function checkLayoutThrashing() {
-    if (!isDevMode)
-        return;
-    // For ES modules, we can't override imports directly
-    // Instead, we'll provide alternative functions that users can opt into
-    console.log('⚠️ Layout thrashing detection is disabled in ES modules.');
-    // Export alternative functions that can be used instead
-    window.measureWithTracking = function (fn) {
-        let isMeasuring = false;
-        let isMutating = false;
-        // Check if we're in a mutate phase
-        if (isMutating) {
-            warnIfLayoutReadInMutate();
-        }
-        isMeasuring = true;
-        try {
-            return measure(fn);
-        }
-        finally {
-            isMeasuring = false;
-        }
-    };
-    window.mutateWithTracking = function (fn) {
-        let isMeasuring = false;
-        let isMutating = false;
-        // Check if we're in a measure phase
-        if (isMeasuring) {
-            warnIfLayoutReadInMutate();
-        }
-        isMutating = true;
-        try {
-            mutate(fn);
-        }
-        finally {
-            isMutating = false;
-        }
-    };
-    console.log('📊 Use window.measureWithTracking() and window.mutateWithTracking() for layout thrashing detection.');
-}
-// Performance monitoring
-export function monitorPerformance() {
-    if (!isDevMode)
-        return;
-    let lastFrameTime = performance.now();
-    let frameCount = 0;
-    let fps = 0;
-    function calculateFPS() {
-        const now = performance.now();
-        const delta = now - lastFrameTime;
-        if (delta >= 1000) {
-            fps = Math.round((frameCount * 1000) / delta);
-            frameCount = 0;
-            lastFrameTime = now;
-            if (fps < 30) {
-                console.warn(`⚠️ Low FPS: ${fps}. Consider optimizing your effects.`);
-            }
-        }
-        frameCount++;
-        requestAnimationFrame(calculateFPS);
-    }
-    calculateFPS();
-}
-// Memory leak detection
-export function detectMemoryLeaks() {
-    if (!isDevMode)
-        return;
-    const originalScopeDispose = getCurrentScope()?.dispose;
-    if (originalScopeDispose) {
-        getCurrentScope().dispose = function () {
-            const beforeCleanupCount = this.cleanups?.length || 0;
-            originalScopeDispose.call(this);
-            const afterCleanupCount = this.cleanups?.length || 0;
-            if (afterCleanupCount > 0) {
-                console.warn(`⚠️ Potential memory leak: ${afterCleanupCount} cleanups remained after scope dispose.`);
-            }
-        };
-    }
-}
-// Initialize dev tools
-export async function initDevTools() {
-    if (!isDevMode)
-        return;
-    await checkLayoutThrashing();
-    monitorPerformance();
-    detectMemoryLeaks();
-    console.log('🔧 Dalila DevTools enabled');
-}
-// Simple signal inspection
-export function inspectSignal(signal) {
-    if (!isDevMode)
-        return { value: signal(), subscribers: 0 };
-    const value = signal();
-    const subscribers = signal.subscribers?.size || 0;
-    return { value, subscribers };
-}
-// Effect tracking
-let effectIdCounter = 0;
-const activeEffects = new Map();
-export function trackEffect(fn) {
-    if (!isDevMode)
-        return () => { };
-    const effectId = effectIdCounter++;
-    const stack = new Error().stack || 'No stack trace';
-    activeEffects.set(effectId, { fn, stack });
-    return () => {
-        activeEffects.delete(effectId);
-    };
-}
-export function getActiveEffects() {
-    if (!isDevMode)
-        return [];
-    return Array.from(activeEffects.entries()).map(([id, { fn, stack }]) => ({
-        id,
-        fn,
-        stack
-    }));
-}
-// Scope inspection
-export function getCurrentScopeInfo() {
-    const scope = getCurrentScope();
-    if (!scope || !isDevMode) {
-        return { cleanupCount: 0, effectCount: 0 };
-    }
-    return {
-        cleanupCount: scope.cleanups?.length || 0,
-        effectCount: getActiveEffects().length
-    };
-}

package/dist/core/for.d.ts

@@ -1,3 +1,42 @@
-export declare function forEach<T>(items: () => T[], template: (item: T, index: () => number) => Node | Node[], keyFn?: (item: T) => string): DocumentFragment;
-export declare function createList<T>(items: () => T[], template: (item: T, index: number) => Node | Node[], keyFn?: (item: T) => string): DocumentFragment;
-export declare function createKeyedElement<K extends keyof HTMLElementTagNameMap>(tag: K, key: string, children?: Node | Node[] | string, attrs?: Record<string, any>): HTMLElementTagNameMap[K];
+interface DisposableFragment extends DocumentFragment {
+    dispose(): void;
+}
+/**
+ * Low-level keyed list rendering with fine-grained reactivity.
+ *
+ * Uses keyed diffing to efficiently update only changed items.
+ * Each item gets its own scope for automatic cleanup.
+ *
+ * @param items - Signal or function returning array of items
+ * @param template - Function that renders each item (receives item and reactive index)
+ * @param keyFn - Optional function to extract unique key from item (defaults to index)
+ *
+ * @example
+ * ```ts
+ * const todos = signal([
+ *   { id: 1, text: 'Learn Dalila' },
+ *   { id: 2, text: 'Build app' }
+ * ]);
+ *
+ * forEach(
+ *   () => todos(),
+ *   (todo, index) => {
+ *     const li = document.createElement('li');
+ *     li.textContent = `${index()}: ${todo.text}`;
+ *     return li;
+ *   },
+ *   (todo) => todo.id.toString()
+ * );
+ * ```
+ *
+ * @internal Prefer createList() for most use cases
+ */
+export declare function forEach<T>(items: () => T[], template: (item: T, index: () => number) => Node | Node[], keyFn?: (item: T, index: number) => string): DisposableFragment;
+/**
+ * Stable API for rendering keyed lists.
+ *
+ * Renders a reactive list with automatic updates when items change.
+ * Only re-renders items that actually changed (keyed diffing).
+ */
+export declare function createList<T>(items: () => T[], template: (item: T, index: number) => Node | Node[], keyFn?: (item: T, index: number) => string): DisposableFragment;
+export {};

package/dist/core/for.js

@@ -1,27 +1,117 @@
 import { effect, signal } from './signal.js';
-// Experimental: low-level keyed list diff. Prefer createList for stable API.
+import { isInDevMode } from './dev.js';
+import { createScope, withScope, getCurrentScope } from './scope.js';
+const autoDisposeByDocument = new WeakMap();
+const getMutationObserverCtor = (doc) => {
+    if (doc.defaultView?.MutationObserver)
+        return doc.defaultView.MutationObserver;
+    if (typeof MutationObserver !== 'undefined')
+        return MutationObserver;
+    return null;
+};
+const registerAutoDispose = (start, end, cleanup) => {
+    const doc = start.ownerDocument;
+    const MutationObserverCtor = getMutationObserverCtor(doc);
+    if (!MutationObserverCtor)
+        return () => { };
+    let ctx = autoDisposeByDocument.get(doc);
+    if (!ctx) {
+        const entries = new Set();
+        const observer = new MutationObserverCtor(() => {
+            entries.forEach(entry => {
+                const connected = entry.start.isConnected && entry.end.isConnected;
+                if (!entry.attached && connected) {
+                    entry.attached = true;
+                    return;
+                }
+                if (entry.attached && !connected)
+                    entry.cleanup();
+            });
+            if (entries.size === 0) {
+                observer.disconnect();
+                autoDisposeByDocument.delete(doc);
+            }
+        });
+        observer.observe(doc, { childList: true, subtree: true });
+        ctx = { observer, entries };
+        autoDisposeByDocument.set(doc, ctx);
+    }
+    const entry = {
+        start,
+        end,
+        cleanup,
+        attached: start.isConnected && end.isConnected
+    };
+    ctx.entries.add(entry);
+    return () => {
+        ctx?.entries.delete(entry);
+        if (ctx && ctx.entries.size === 0) {
+            ctx.observer.disconnect();
+            autoDisposeByDocument.delete(doc);
+        }
+    };
+};
+/**
+ * Low-level keyed list rendering with fine-grained reactivity.
+ *
+ * Uses keyed diffing to efficiently update only changed items.
+ * Each item gets its own scope for automatic cleanup.
+ *
+ * @param items - Signal or function returning array of items
+ * @param template - Function that renders each item (receives item and reactive index)
+ * @param keyFn - Optional function to extract unique key from item (defaults to index)
+ *
+ * @example
+ * ```ts
+ * const todos = signal([
+ *   { id: 1, text: 'Learn Dalila' },
+ *   { id: 2, text: 'Build app' }
+ * ]);
+ *
+ * forEach(
+ *   () => todos(),
+ *   (todo, index) => {
+ *     const li = document.createElement('li');
+ *     li.textContent = `${index()}: ${todo.text}`;
+ *     return li;
+ *   },
+ *   (todo) => todo.id.toString()
+ * );
+ * ```
+ *
+ * @internal Prefer createList() for most use cases
+ */
 export function forEach(items, template, keyFn) {
     const start = document.createComment('for:start');
     const end = document.createComment('for:end');
     let currentItems = [];
-    let currentIndex = signal(0);
+    let disposeEffect = null;
+    const parentScope = getCurrentScope();
+    let disposed = false;
+    let stopAutoDispose = null;
     const getKey = (item, index) => {
-        if (keyFn) {
-            return keyFn(item);
-        }
-        // Default key is index if no key function provided
-        return index.toString();
+        if (keyFn)
+            return keyFn(item, index);
+        // Using index as key is an anti-pattern for dynamic lists
+        // but we allow it as a fallback. Items will be re-rendered on reorder.
+        return `__idx_${index}`;
     };
     const removeNode = (node) => {
         if (node.parentNode)
             node.parentNode.removeChild(node);
     };
-    const removeRange = (startNode, endNode) => {
-        let node = startNode;
+    const removeRange = (keyedItem) => {
+        // Dispose scope first to cleanup effects/listeners
+        if (keyedItem.scope) {
+            keyedItem.scope.dispose();
+            keyedItem.scope = null;
+        }
+        // Remove DOM nodes (including markers)
+        let node = keyedItem.start;
         while (node) {
             const next = node.nextSibling;
             removeNode(node);
-            if (node === endNode)
+            if (node === keyedItem.end)
                 break;
             node = next;
         }
@@ -38,120 +128,184 @@ export function forEach(items, template, keyFn) {
         const parent = referenceNode.parentNode;
         if (!parent)
             return;
-        const fragment = document.createDocumentFragment();
         let node = startNode;
         while (node) {
             const next = node.nextSibling;
-            fragment.appendChild(node);
+            parent.insertBefore(node, referenceNode);
             if (node === endNode)
                 break;
             node = next;
         }
-        parent.insertBefore(fragment, referenceNode);
     };
+    let hasValidatedOnce = false;
+    const throwDuplicateKey = (key, scheduleFatal) => {
+        const error = new Error(`[Dalila] Duplicate key "${key}" detected in forEach. ` +
+            `Keys must be unique within the same list. Check your keyFn implementation.`);
+        if (scheduleFatal) {
+            queueMicrotask(() => {
+                throw error;
+            });
+        }
+        throw error;
+    };
+    const validateNoDuplicateKeys = (arr) => {
+        if (!isInDevMode())
+            return;
+        const scheduleFatal = hasValidatedOnce;
+        hasValidatedOnce = true;
+        const seenKeys = new Set();
+        arr.forEach((item, index) => {
+            const key = getKey(item, index);
+            if (seenKeys.has(key)) {
+                throwDuplicateKey(key, scheduleFatal);
+            }
+            seenKeys.add(key);
+        });
+    };
+    const disposeItemScope = (item) => {
+        if (!item.scope)
+            return;
+        item.scope.dispose();
+        item.scope = null;
+    };
+    const cleanup = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        stopAutoDispose?.();
+        stopAutoDispose = null;
+        disposeEffect?.();
+        disposeEffect = null;
+        currentItems.forEach(item => {
+            removeRange(item);
+        });
+        currentItems = [];
+        removeNode(start);
+        removeNode(end);
+    };
+    // Validate first render synchronously (let throw escape in dev)
+    validateNoDuplicateKeys(items());
     const update = () => {
+        if (disposed)
+            return;
         const newItems = items();
+        // Validate again on updates (will be caught by effect error handler)
+        validateNoDuplicateKeys(newItems);
         const oldMap = new Map();
         currentItems.forEach(item => oldMap.set(item.key, item));
         const nextItems = [];
-        const needsUpdate = new Set();
+        const itemsToUpdate = new Set();
+        const seenNextKeys = new Set();
+        // Phase 1: Build next list + detect updates/new
         newItems.forEach((item, index) => {
             const key = getKey(item, index);
+            if (seenNextKeys.has(key))
+                return; // prod-mode: ignore dup keys silently
+            seenNextKeys.add(key);
             const existing = oldMap.get(key);
             if (existing) {
                 if (existing.value !== item) {
-                    needsUpdate.add(key);
+                    itemsToUpdate.add(key);
                     existing.value = item;
                 }
                 nextItems.push(existing);
             }
             else {
-                needsUpdate.add(key);
+                itemsToUpdate.add(key);
                 nextItems.push({
                     key,
                     value: item,
-                    start: document.createComment(`for:item:start:${key}`),
-                    end: document.createComment(`for:item:end:${key}`)
+                    start: document.createComment(`for:${key}:start`),
+                    end: document.createComment(`for:${key}:end`),
+                    scope: null,
+                    indexSignal: signal(index)
                 });
             }
         });
-        const nextKeys = new Set(nextItems.map(item => item.key));
+        // Phase 2: Remove items no longer present
+        const nextKeys = new Set(nextItems.map(i => i.key));
         currentItems.forEach(item => {
-            if (!nextKeys.has(item.key)) {
-                removeRange(item.start, item.end);
-            }
+            if (!nextKeys.has(item.key))
+                removeRange(item);
         });
+        // Phase 3: Move/insert items to correct positions
         const parent = end.parentNode;
         if (parent) {
             let cursor = start;
             nextItems.forEach(item => {
-                const inDom = item.start.parentNode && item.end.parentNode;
-                const referenceNode = cursor.nextSibling || end;
+                const nextSibling = cursor.nextSibling;
+                const inDom = item.start.parentNode === parent;
                 if (!inDom) {
+                    const referenceNode = nextSibling || end;
                     referenceNode.before(item.start, item.end);
                 }
-                else if (referenceNode !== item.start) {
+                else if (nextSibling !== item.start) {
+                    const referenceNode = nextSibling || end;
                     moveRangeBefore(item.start, item.end, referenceNode);
                 }
                 cursor = item.end;
             });
         }
-        nextItems.forEach((item, index) => {
-            if (!needsUpdate.has(item.key))
+        // Phase 4: Dispose scopes and clear content for changed items
+        nextItems.forEach(item => {
+            if (!itemsToUpdate.has(item.key))
                 return;
+            disposeItemScope(item);
             clearBetween(item.start, item.end);
-            const templateResult = template(item.value, () => index);
-            const nodes = Array.isArray(templateResult) ? templateResult : [templateResult];
-            item.end.before(...nodes);
+        });
+        // Phase 5: Update reactive indices for ALL items
+        nextItems.forEach((item, index) => {
+            item.indexSignal.set(index);
+        });
+        // Phase 6: Render changed items
+        nextItems.forEach(item => {
+            if (!itemsToUpdate.has(item.key))
+                return;
+            item.scope = createScope();
+            withScope(item.scope, () => {
+                const indexGetter = () => item.indexSignal();
+                const templateResult = template(item.value, indexGetter);
+                const nodes = Array.isArray(templateResult) ? templateResult : [templateResult];
+                item.end.before(...nodes);
+            });
         });
         currentItems = nextItems;
     };
-    // Initial render
-    effect(() => {
-        update();
-    });
+    // IMPORTANT: append markers BEFORE creating the effect,
+    // so a synchronous effect run can still render into the fragment safely.
     const frag = document.createDocumentFragment();
     frag.append(start, end);
+    frag.dispose = cleanup;
+    // Run update reactively and capture dispose
+    disposeEffect = effect(() => {
+        if (disposed)
+            return;
+        update();
+    });
+    // Cleanup on parent scope disposal
+    if (parentScope) {
+        parentScope.onCleanup(cleanup);
+    }
+    else {
+        stopAutoDispose = registerAutoDispose(start, end, cleanup);
+        if (isInDevMode()) {
+            console.warn('[Dalila] forEach() called outside of a scope. ' +
+                'The effect will not be tied to a scope. ' +
+                'It will auto-dispose when removed from the DOM, ' +
+                'or call fragment.dispose() for manual cleanup if needed.');
+        }
+    }
     return frag;
 }
-// Simplified version for common use case
+/**
+ * Stable API for rendering keyed lists.
+ *
+ * Renders a reactive list with automatic updates when items change.
+ * Only re-renders items that actually changed (keyed diffing).
+ */
 export function createList(items, template, keyFn) {
     return forEach(items, (item, index) => {
         const idx = index();
         return template(item, idx);
     }, keyFn);
 }
-// DOM element with key support for list items
-export function createKeyedElement(tag, key, children, attrs) {
-    const element = document.createElement(tag);
-    element.setAttribute('data-key', key);
-    // Set attributes
-    if (attrs) {
-        Object.entries(attrs).forEach(([key, value]) => {
-            if (key === 'class') {
-                element.className = value;
-            }
-            else if (key === 'style' && typeof value === 'object') {
-                Object.assign(element.style, value);
-            }
-            else if (key.startsWith('on') && typeof value === 'function') {
-                const eventName = key.slice(2).toLowerCase();
-                element.addEventListener(eventName, value);
-            }
-            else {
-                element.setAttribute(key, String(value));
-            }
-        });
-    }
-    // Add children
-    if (children !== undefined) {
-        if (typeof children === 'string') {
-            element.textContent = children;
-        }
-        else {
-            const nodes = Array.isArray(children) ? children : [children];
-            element.append(...nodes);
-        }
-    }
-    return element;
-}

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./scope.js";
 export * from "./signal.js";
-export * from "./watch.js";
+export { watch, onMount, onCleanup, useEvent, useInterval, useTimeout, useFetch } from "./watch.js";
 export * from "./when.js";
 export * from "./match.js";
 export * from "./for.js";

package/dist/core/index.js

@@ -1,6 +1,6 @@
 export * from "./scope.js";
 export * from "./signal.js";
-export * from "./watch.js";
+export { watch, onMount, onCleanup, useEvent, useInterval, useTimeout, useFetch } from "./watch.js";
 export * from "./when.js";
 export * from "./match.js";
 export * from "./for.js";

package/dist/core/watch-testing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Testing utilities for watch.ts
+ *
+ * This file is NOT exported in the public API (src/index.ts).
+ * It should only be imported directly by test files.
+ *
+ * @internal
+ */
+/**
+ * Reset all warning flags to their initial state.
+ * Use this in tests to ensure deterministic warning behavior.
+ */
+export declare function resetWarnings(): void;

package/dist/core/watch-testing.js

@@ -0,0 +1,16 @@
+/**
+ * Testing utilities for watch.ts
+ *
+ * This file is NOT exported in the public API (src/index.ts).
+ * It should only be imported directly by test files.
+ *
+ * @internal
+ */
+import { __resetWarningsForTests } from './watch.js';
+/**
+ * Reset all warning flags to their initial state.
+ * Use this in tests to ensure deterministic warning behavior.
+ */
+export function resetWarnings() {
+    __resetWarningsForTests();
+}

package/dist/core/watch.d.ts

@@ -1,19 +1,81 @@
 /**
- * Watch a DOM node and run an effect while it's connected.
+ * Reset warning flags (used by src/internal/watch-testing.ts for deterministic tests).
+ * @internal
+ */
+export declare function __resetWarningsForTests(): void;
+/**
+ * watch(node, fn)
+ *
+ * Runs `fn` inside a reactive effect while `node` is connected to the document.
+ * - Signal reads inside `fn` are tracked (because `fn` runs inside effect()).
+ * - When the node disconnects, the effect is disposed.
+ * - If the node reconnects later, the effect may start again (best-effort, based on DOM mutations).
  *
- * Fixes applied:
- * 1) Late-start effects now run inside the original scope (captured on watch()).
- * 2) watches uses WeakMap<Node,...> so we don't keep detached nodes alive.
- * 3) Observer disconnect uses ctx.watchCount (since WeakMap has no .size).
+ * Implementation notes / fixes:
+ * 1) Scope capture: the scope at watch() time is stored on the entry so effects that start later
+ *    still get created "inside" the original scope (fixes late-start effects created outside scope).
+ * 2) Memory safety: watches uses WeakMap<Node, ...> so detached nodes are not kept alive.
+ * 3) Observer lifecycle: we track ctx.watchCount (WeakMap has no .size) to know when to disconnect.
  */
 export declare function watch(node: Node, fn: () => void): () => void;
+/**
+ * onMount(fn)
+ *
+ * Executes fn immediately. Minimal semantic helper to document mount-time logic in DOM-first code.
+ * Unlike React, there's no deferred execution or batching — it runs synchronously.
+ */
 export declare function onMount(fn: () => void): void;
+/**
+ * onCleanup(fn)
+ *
+ * Registers fn to run when the current scope is disposed.
+ * If called outside a scope, fn is never called (no-op).
+ */
 export declare function onCleanup(fn: () => void): void;
+/**
+ * useEvent(target, type, handler, options?)
+ *
+ * Attaches an event listener and returns an idempotent dispose() function.
+ * - Inside a scope: listener is removed automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export declare function useEvent<T extends EventTarget>(target: T, type: string, handler: (event: Event) => void, options?: AddEventListenerOptions): () => void;
+/**
+ * useInterval(fn, ms)
+ *
+ * Starts an interval and returns an idempotent dispose() function.
+ * - Inside a scope: interval is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export declare function useInterval(fn: () => void, ms: number): () => void;
+/**
+ * useTimeout(fn, ms)
+ *
+ * Starts a timeout and returns an idempotent dispose() function.
+ * - Inside a scope: timeout is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export declare function useTimeout(fn: () => void, ms: number): () => void;
+/**
+ * useFetch(url, options)
+ *
+ * Small convenience for "fetch + reactive state + abort" built on effectAsync().
+ * Returns { data, loading, error, dispose }.
+ *
+ * Behavior:
+ * - Runs the fetch inside effectAsync, which provides an AbortSignal.
+ * - If url is a function, it tracks signal reads (reactive).
+ * - Calling dispose() aborts the in-flight request (via effectAsync's signal).
+ * - Inside a scope: auto-disposed on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ *
+ * Limitations:
+ * - No refresh(), no caching, no invalidation.
+ * - For those features, use createResource / query().
+ */
 export declare function useFetch<T>(url: string | (() => string), options?: RequestInit): {
     data: () => T | null;
     loading: () => boolean;
     error: () => Error | null;
+    dispose: () => void;
 };

package/dist/core/watch.js

@@ -10,6 +10,14 @@ const documentWatchers = new WeakMap();
  */
 let hasWarnedNoScope = false;
 const warnedFunctions = new Set();
+/**
+ * Reset warning flags (used by src/internal/watch-testing.ts for deterministic tests).
+ * @internal
+ */
+export function __resetWarningsForTests() {
+    warnedFunctions.clear();
+    hasWarnedNoScope = false;
+}
 /**
  * Walk a subtree recursively, calling visitor for each node.
  * Supports any Node type (Element, Text, Comment, etc.) via childNodes.
@@ -23,8 +31,12 @@ function walkSubtree(root, visitor) {
     }
 }
 /**
- * Start a watch entry effect in the entry's captured scope (if any).
- * This fixes the critical bug where late-start effects were created outside scope.
+ * Start a watch entry effect inside the entry's captured scope (if any).
+ *
+ * Why:
+ * - `effect()` captures getCurrentScope() at creation time.
+ * - watch entries can start later (when a node becomes connected), so we must re-enter
+ *   the original scope to preserve cleanup semantics.
  */
 function startEntryEffect(entry) {
     if (entry.effectStarted || entry.cleanup)
@@ -105,12 +117,18 @@ function getDocumentWatchContext(doc) {
     return ctx;
 }
 /**
- * Watch a DOM node and run an effect while it's connected.
+ * watch(node, fn)
  *
- * Fixes applied:
- * 1) Late-start effects now run inside the original scope (captured on watch()).
- * 2) watches uses WeakMap<Node,...> so we don't keep detached nodes alive.
- * 3) Observer disconnect uses ctx.watchCount (since WeakMap has no .size).
+ * Runs `fn` inside a reactive effect while `node` is connected to the document.
+ * - Signal reads inside `fn` are tracked (because `fn` runs inside effect()).
+ * - When the node disconnects, the effect is disposed.
+ * - If the node reconnects later, the effect may start again (best-effort, based on DOM mutations).
+ *
+ * Implementation notes / fixes:
+ * 1) Scope capture: the scope at watch() time is stored on the entry so effects that start later
+ *    still get created "inside" the original scope (fixes late-start effects created outside scope).
+ * 2) Memory safety: watches uses WeakMap<Node, ...> so detached nodes are not kept alive.
+ * 3) Observer lifecycle: we track ctx.watchCount (WeakMap has no .size) to know when to disconnect.
  */
 export function watch(node, fn) {
     const currentScope = getCurrentScope();
@@ -160,9 +178,9 @@ export function watch(node, fn) {
         const entries = ctx.watches.get(node);
         if (entries) {
             entries.delete(entry);
-            // If empty, clear to drop strong refs to entries; key removal is handled by WeakMap GC.
+            // If empty, delete the entry from WeakMap to free the Set immediately
             if (entries.size === 0)
-                entries.clear();
+                ctx.watches.delete(node);
         }
         // Decrement active watch count and disconnect observer if none left
         ctx.watchCount--;
@@ -177,14 +195,33 @@ export function watch(node, fn) {
     }
     return dispose;
 }
+/**
+ * onMount(fn)
+ *
+ * Executes fn immediately. Minimal semantic helper to document mount-time logic in DOM-first code.
+ * Unlike React, there's no deferred execution or batching — it runs synchronously.
+ */
 export function onMount(fn) {
     fn();
 }
+/**
+ * onCleanup(fn)
+ *
+ * Registers fn to run when the current scope is disposed.
+ * If called outside a scope, fn is never called (no-op).
+ */
 export function onCleanup(fn) {
     const scope = getCurrentScope();
     if (scope)
         scope.onCleanup(fn);
 }
+/**
+ * useEvent(target, type, handler, options?)
+ *
+ * Attaches an event listener and returns an idempotent dispose() function.
+ * - Inside a scope: listener is removed automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export function useEvent(target, type, handler, options) {
     const scope = getCurrentScope();
     if (!scope && !warnedFunctions.has('useEvent')) {
@@ -204,6 +241,13 @@ export function useEvent(target, type, handler, options) {
         scope.onCleanup(dispose);
     return dispose;
 }
+/**
+ * useInterval(fn, ms)
+ *
+ * Starts an interval and returns an idempotent dispose() function.
+ * - Inside a scope: interval is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export function useInterval(fn, ms) {
     const scope = getCurrentScope();
     if (!scope && !warnedFunctions.has('useInterval')) {
@@ -223,6 +267,13 @@ export function useInterval(fn, ms) {
         scope.onCleanup(dispose);
     return dispose;
 }
+/**
+ * useTimeout(fn, ms)
+ *
+ * Starts a timeout and returns an idempotent dispose() function.
+ * - Inside a scope: timeout is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
 export function useTimeout(fn, ms) {
     const scope = getCurrentScope();
     if (!scope && !warnedFunctions.has('useTimeout')) {
@@ -242,12 +293,34 @@ export function useTimeout(fn, ms) {
         scope.onCleanup(dispose);
     return dispose;
 }
-// Async effect with fetch support and automatic abort
+/**
+ * useFetch(url, options)
+ *
+ * Small convenience for "fetch + reactive state + abort" built on effectAsync().
+ * Returns { data, loading, error, dispose }.
+ *
+ * Behavior:
+ * - Runs the fetch inside effectAsync, which provides an AbortSignal.
+ * - If url is a function, it tracks signal reads (reactive).
+ * - Calling dispose() aborts the in-flight request (via effectAsync's signal).
+ * - Inside a scope: auto-disposed on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ *
+ * Limitations:
+ * - No refresh(), no caching, no invalidation.
+ * - For those features, use createResource / query().
+ */
 export function useFetch(url, options) {
+    const scope = getCurrentScope();
+    if (!scope && !warnedFunctions.has('useFetch')) {
+        warnedFunctions.add('useFetch');
+        console.warn('[Dalila] useFetch() called outside scope. ' +
+            'Request will not auto-cleanup. Call the returned dispose() function manually.');
+    }
     const data = signal(null);
     const loading = signal(false);
     const error = signal(null);
-    effectAsync(async (signal) => {
+    const dispose = effectAsync(async (signal) => {
         try {
             loading.set(true);
             error.set(null);
@@ -259,7 +332,7 @@ export function useFetch(url, options) {
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
-            const result = await response.json();
+            const result = (await response.json());
             data.set(result);
         }
         catch (err) {
@@ -273,5 +346,8 @@ export function useFetch(url, options) {
             }
         }
     });
-    return { data, loading, error };
+    // Match the other lifecycle helpers: if we are inside a scope, dispose automatically.
+    if (scope)
+        scope.onCleanup(dispose);
+    return { data, loading, error, dispose };
 }

package/dist/internal/watch-testing.d.ts

@@ -0,0 +1 @@
+export declare function resetWarnings(): void;

package/dist/internal/watch-testing.js

@@ -0,0 +1,8 @@
+/**
+ * Testing utilities for watch.ts
+ * @internal
+ */
+import { __resetWarningsForTests } from '../core/watch.js';
+export function resetWarnings() {
+    __resetWarningsForTests();
+}

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "dalila",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "DOM-first reactive framework based on signals",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",