dalila 1.3.2 → 1.4.0

package/dist/context/auto-scope.d.ts

@@ -13,6 +13,7 @@
  * - Still keep things lifecycle-safe: the global scope can be disposed on page unload.
  */
 import { type Scope } from '../core/scope.js';
+import { type Signal } from '../core/signal.js';
 import { createContext, type ContextToken, type TryInjectResult } from './context.js';
 export type AutoScopePolicy = "warn" | "throw" | "silent";
 export declare function setAutoScopePolicy(policy: AutoScopePolicy): void;
@@ -99,4 +100,68 @@ export declare function hasGlobalScope(): boolean;
  * Intended for tests to ensure isolation between runs.
  */
 export declare function resetGlobalScope(): void;
+/**
+ * Creates a reactive context that wraps a signal.
+ *
+ * This is the recommended way to share reactive state across scopes.
+ * It combines the hierarchical lookup of Context with the reactivity of Signals.
+ *
+ * Example:
+ * ```ts
+ * const Theme = createSignalContext("theme", "dark");
+ *
+ * scope(() => {
+ *   // Parent scope: create and provide the signal
+ *   const theme = Theme.provide();
+ *
+ *   effect(() => {
+ *     console.log("Theme:", theme()); // Reactive!
+ *   });
+ *
+ *   theme.set("light"); // Updates propagate to all consumers
+ * });
+ *
+ * // Child scope somewhere in the tree
+ * scope(() => {
+ *   const theme = Theme.inject(); // Get the signal from parent
+ *   console.log(theme()); // "light"
+ * });
+ * ```
+ */
+export interface SignalContext<T> {
+    /**
+     * Create a signal with the initial value and provide it in the current scope.
+     * Returns the signal for immediate use.
+     *
+     * @param initialValue - Override the default initial value (optional)
+     */
+    provide: (initialValue?: T) => Signal<T>;
+    /**
+     * Inject the signal from an ancestor scope.
+     * Throws if no provider exists in the scope hierarchy.
+     */
+    inject: () => Signal<T>;
+    /**
+     * Try to inject the signal from an ancestor scope.
+     * Returns { found: true, signal } or { found: false, signal: undefined }.
+     */
+    tryInject: () => {
+        found: true;
+        signal: Signal<T>;
+    } | {
+        found: false;
+        signal: undefined;
+    };
+    /**
+     * The underlying context token (for advanced use cases).
+     */
+    token: ContextToken<Signal<T>>;
+}
+/**
+ * Create a reactive context that wraps a signal.
+ *
+ * @param name - Debug name for the context
+ * @param defaultValue - Default initial value for the signal
+ */
+export declare function createSignalContext<T>(name: string, defaultValue: T): SignalContext<T>;
 export { createContext };

package/dist/context/auto-scope.js

@@ -14,6 +14,7 @@
  */
 import { getCurrentScope, createScope, isScopeDisposed, withScope } from '../core/scope.js';
 import { isInDevMode } from '../core/dev.js';
+import { signal as createSignal } from '../core/signal.js';
 import { createContext, provide as rawProvide, tryInject as rawTryInject, debugListAvailableContexts, } from './context.js';
 /**
  * Symbol key for storing the global root scope.
@@ -349,5 +350,32 @@ export function resetGlobalScope() {
     warnedGlobalProvide = false;
     autoScopePolicy = "throw";
 }
+/**
+ * Create a reactive context that wraps a signal.
+ *
+ * @param name - Debug name for the context
+ * @param defaultValue - Default initial value for the signal
+ */
+export function createSignalContext(name, defaultValue) {
+    const token = createContext(name);
+    return {
+        provide(initialValue) {
+            const sig = createSignal(initialValue !== undefined ? initialValue : defaultValue);
+            provide(token, sig);
+            return sig;
+        },
+        inject() {
+            return inject(token);
+        },
+        tryInject() {
+            const result = tryInject(token);
+            if (result.found) {
+                return { found: true, signal: result.value };
+            }
+            return { found: false, signal: undefined };
+        },
+        token,
+    };
+}
 // Re-export createContext for convenience.
 export { createContext };

package/dist/context/index.d.ts

@@ -1,2 +1,2 @@
 export { createContext, setDeepHierarchyWarnDepth, listAvailableContexts, type ContextToken, type TryInjectResult, } from "./context.js";
-export { provide, inject, tryInject, scope, createProvider, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";
+export { provide, inject, tryInject, scope, createProvider, createSignalContext, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, type SignalContext, } from "./auto-scope.js";

package/dist/context/index.js

@@ -1,2 +1,2 @@
 export { createContext, setDeepHierarchyWarnDepth, listAvailableContexts, } from "./context.js";
-export { provide, inject, tryInject, scope, createProvider, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";
+export { provide, inject, tryInject, scope, createProvider, createSignalContext, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";

package/dist/context/raw.d.ts

@@ -1,2 +1,2 @@
-export { createContext, type ContextToken } from "./context.js";
+export { createContext, setDeepHierarchyWarnDepth, type ContextToken, type TryInjectResult, } from "./context.js";
 export { provide, inject, tryInject, injectMeta, debugListAvailableContexts, listAvailableContexts, } from "./context.js";

package/dist/context/raw.js

@@ -1,2 +1,2 @@
-export { createContext } from "./context.js";
+export { createContext, setDeepHierarchyWarnDepth, } from "./context.js";
 export { provide, inject, tryInject, injectMeta, debugListAvailableContexts, listAvailableContexts, } from "./context.js";

package/dist/core/dev.d.ts

@@ -1,2 +1,7 @@
 export declare function setDevMode(enabled: boolean): void;
 export declare function isInDevMode(): boolean;
+/**
+ * Initialize dev tools. Currently just enables dev mode.
+ * Returns a promise for future async initialization support.
+ */
+export declare function initDevTools(): Promise<void>;

package/dist/core/dev.js

@@ -5,3 +5,10 @@ export function setDevMode(enabled) {
 export function isInDevMode() {
     return isDevMode;
 }
+/**
+ * Initialize dev tools. Currently just enables dev mode.
+ * Returns a promise for future async initialization support.
+ */
+export async function initDevTools() {
+    setDevMode(true);
+}

package/dist/core/index.d.ts

@@ -10,5 +10,5 @@ export * from "./key.js";
 export * from "./resource.js";
 export * from "./query.js";
 export * from "./mutation.js";
-export * from "./store.js";
 export { batch, measure, mutate, configureScheduler, getSchedulerConfig } from "./scheduler.js";
+export { persist, createJSONStorage, clearPersisted, createPreloadScript, createThemeScript, type StateStorage, type PersistOptions, type Serializer, type PreloadScriptOptions } from "./persist.js";

package/dist/core/index.js

@@ -10,5 +10,5 @@ export * from "./key.js";
 export * from "./resource.js";
 export * from "./query.js";
 export * from "./mutation.js";
-export * from "./store.js";
 export { batch, measure, mutate, configureScheduler, getSchedulerConfig } from "./scheduler.js";
+export { persist, createJSONStorage, clearPersisted, createPreloadScript, createThemeScript } from "./persist.js";

package/dist/core/persist.d.ts

@@ -0,0 +1,63 @@
+import { type Signal } from './signal.js';
+/**
+ * Storage interface (compatible with localStorage, sessionStorage, etc.)
+ */
+export interface StateStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem?(key: string): void | Promise<void>;
+}
+/**
+ * Serialization interface
+ */
+export interface Serializer<T> {
+    serialize(value: T): string;
+    deserialize(value: string): T;
+}
+/**
+ * Persist options
+ */
+export interface PersistOptions<T> {
+    name: string;
+    storage?: StateStorage;
+    serializer?: Serializer<T>;
+    version?: number;
+    migrate?: (persistedState: unknown, version: number) => T;
+    merge?: 'replace' | 'shallow';
+    onRehydrate?: (state: T) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Dev-server only hint (not used by runtime yet).
+     * Kept for forward-compat with preload injection.
+     */
+    preload?: boolean;
+}
+/**
+ * Create a persisted signal that automatically syncs with storage.
+ */
+export declare function persist<T>(baseSignal: Signal<T>, options: PersistOptions<T>): Signal<T>;
+/**
+ * Helper to create JSON storage wrapper
+ */
+export declare function createJSONStorage(getStorage: () => StateStorage): StateStorage;
+/**
+ * Clear persisted data for a given key
+ */
+export declare function clearPersisted(name: string, storage?: StateStorage): void;
+/**
+ * Options for preload script generation
+ */
+export interface PreloadScriptOptions {
+    storageKey: string;
+    defaultValue: string;
+    target?: 'documentElement' | 'body';
+    attribute?: string;
+    storageType?: 'localStorage' | 'sessionStorage';
+}
+/**
+ * Generate a minimal inline script to prevent FOUC.
+ *
+ * NOTE: Assumes the value in storage was JSON serialized (default serializer).
+ */
+export declare function createPreloadScript(options: PreloadScriptOptions): string;
+export declare function createThemeScript(storageKey: string, defaultTheme?: string): string;

package/dist/core/persist.js

@@ -0,0 +1,371 @@
+import { effect } from './signal.js';
+import { getCurrentScope } from './scope.js';
+const defaultSerializer = {
+    serialize: JSON.stringify,
+    deserialize: JSON.parse,
+};
+function isPromiseLike(v) {
+    return !!v && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function';
+}
+function safeDefaultStorage() {
+    if (typeof window === 'undefined')
+        return undefined;
+    try {
+        return window.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function parseVersion(v) {
+    if (typeof v !== 'string')
+        return 0;
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+function isPlainObject(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    if (Array.isArray(v))
+        return false;
+    return Object.getPrototypeOf(v) === Object.prototype;
+}
+/**
+ * Create a persisted signal that automatically syncs with storage.
+ */
+export function persist(baseSignal, options) {
+    const { name, storage = safeDefaultStorage(), serializer = defaultSerializer, version, merge = 'replace', onRehydrate, onError, migrate, } = options;
+    if (!name) {
+        throw new Error('[Dalila] persist() requires a "name" option');
+    }
+    if (!storage) {
+        console.warn(`[Dalila] persist(): storage not available for "${name}", persistence disabled`);
+        return baseSignal;
+    }
+    const storageKey = name;
+    const versionKey = version !== undefined ? `${name}:version` : undefined;
+    // ---- Core safety flags ----
+    // hydrated=false blocks writes so we don't overwrite storage before async read resolves.
+    let hydrated = false;
+    // becomes true if user changes signal before hydration completes
+    let dirtyBeforeHydrate = false;
+    /**
+     * Hydration write guard:
+     * The dirty listener below uses baseSignal.on(), which would also fire for the
+     * hydration set() itself. This guard prevents hydration from counting as "user dirty".
+     */
+    let isHydrationWrite = false;
+    // temporary listener to detect changes before hydration completes
+    let removeDirtyListener = null;
+    /**
+     * Write-back dedupe (best effort):
+     * Avoid rewriting the same serialized value back to storage after hydration.
+     *
+     * - lastSaved: what we believe is currently in storage
+     * - pendingSaved: what we've already queued to write
+     *
+     * This prevents: storage -> hydrate -> effect runs -> serialize -> setItem(same value)
+     */
+    let lastSaved = null;
+    let pendingSaved = null;
+    // Same idea for version key (when enabled)
+    let lastSavedVersion = null;
+    let pendingSavedVersion = null;
+    const handleError = (err, ctx) => {
+        const e = toError(err);
+        if (onError)
+            onError(e);
+        else
+            console.error(`[Dalila] persist(): ${ctx} "${name}"`, e);
+    };
+    const applyHydration = (value) => {
+        // Ensure dirty listener does not treat hydration as user mutation.
+        const setHydratedValue = (next) => {
+            isHydrationWrite = true;
+            try {
+                baseSignal.set(next);
+            }
+            finally {
+                isHydrationWrite = false;
+            }
+        };
+        if (merge === 'shallow' && isPlainObject(value)) {
+            const current = baseSignal.peek();
+            if (isPlainObject(current)) {
+                setHydratedValue({ ...current, ...value });
+                return;
+            }
+        }
+        setHydratedValue(value);
+    };
+    // Ensure async writes don't land out-of-order (queue them)
+    let writeChain = Promise.resolve();
+    const queueWrite = (fn) => {
+        writeChain = writeChain
+            .then(() => fn())
+            .catch((err) => {
+            // If a queued write fails, clear pending so future writes aren't blocked.
+            pendingSaved = null;
+            pendingSavedVersion = null;
+            handleError(err, 'failed to save');
+        });
+    };
+    /**
+     * Enqueue write with dedupe:
+     * - if value/version already matches what's saved (or already queued), no-op.
+     */
+    const enqueuePersist = (serialized, versionStr) => {
+        const needsValue = serialized !== lastSaved && serialized !== pendingSaved;
+        const needsVersion = !!versionKey &&
+            versionStr !== null &&
+            versionStr !== lastSavedVersion &&
+            versionStr !== pendingSavedVersion;
+        if (!needsValue && !needsVersion)
+            return;
+        if (needsValue)
+            pendingSaved = serialized;
+        if (needsVersion)
+            pendingSavedVersion = versionStr;
+        queueWrite(async () => {
+            // Write value
+            if (needsValue) {
+                const r1 = storage.setItem(storageKey, serialized);
+                if (isPromiseLike(r1))
+                    await r1;
+                lastSaved = serialized;
+                if (pendingSaved === serialized)
+                    pendingSaved = null;
+            }
+            // Write version
+            if (needsVersion && versionKey && versionStr !== null) {
+                const r2 = storage.setItem(versionKey, versionStr);
+                if (isPromiseLike(r2))
+                    await r2;
+                lastSavedVersion = versionStr;
+                if (pendingSavedVersion === versionStr)
+                    pendingSavedVersion = null;
+            }
+        });
+    };
+    const persistValue = (value) => {
+        // Don't write until hydration finishes (prevents overwriting stored state).
+        if (!hydrated)
+            return;
+        let serialized;
+        try {
+            serialized = serializer.serialize(value);
+        }
+        catch (err) {
+            handleError(err, 'failed to serialize');
+            return;
+        }
+        const versionStr = versionKey ? String(version) : null;
+        enqueuePersist(serialized, versionStr);
+    };
+    /**
+     * Hydrate from already-read storage strings.
+     * For sync storage we can read versionKey synchronously too.
+     */
+    const hydrateFromStored = (storedValue, storedVersionRaw) => {
+        // Track current storage contents to avoid immediate write-back.
+        lastSaved = storedValue;
+        pendingSaved = null;
+        if (versionKey) {
+            lastSavedVersion = storedVersionRaw;
+            pendingSavedVersion = null;
+        }
+        const deserialized = serializer.deserialize(storedValue);
+        if (version !== undefined && versionKey && migrate) {
+            const storedVersion = parseVersion(storedVersionRaw);
+            if (storedVersion !== version) {
+                const migrated = migrate(deserialized, storedVersion);
+                applyHydration(migrated);
+                // Save migrated data to storage (don't leave old data with new version)
+                let migratedSerialized;
+                try {
+                    migratedSerialized = serializer.serialize(baseSignal.peek());
+                }
+                catch (err) {
+                    handleError(err, 'failed to serialize migrated data');
+                    return;
+                }
+                enqueuePersist(migratedSerialized, String(version));
+                return;
+            }
+        }
+        applyHydration(deserialized);
+    };
+    const finalizeHydration = (didUserChangeBefore) => {
+        hydrated = true;
+        // Remove temporary dirty listener (no longer needed after hydration)
+        if (removeDirtyListener) {
+            removeDirtyListener();
+            removeDirtyListener = null;
+        }
+        // If user changed before hydrate finished, we must persist current value at least once,
+        // because the change already happened while hydrated=false and won't re-trigger.
+        if (didUserChangeBefore) {
+            persistValue(baseSignal.peek());
+        }
+        if (onRehydrate) {
+            try {
+                onRehydrate(baseSignal.peek());
+            }
+            catch (err) {
+                handleError(err, 'onRehydrate threw');
+            }
+        }
+    };
+    const hydrate = () => {
+        try {
+            const stored = storage.getItem(storageKey);
+            // async storage
+            if (isPromiseLike(stored)) {
+                return stored
+                    .then(async (storedValue) => {
+                    if (storedValue === null) {
+                        finalizeHydration(dirtyBeforeHydrate);
+                        return;
+                    }
+                    // Track value even if we skip applying due to dirty (helps dedupe correctness).
+                    lastSaved = storedValue;
+                    pendingSaved = null;
+                    // If user changed before hydration finished, prefer local state:
+                    // do NOT apply storedValue (prevents "rollback" to old storage).
+                    if (dirtyBeforeHydrate) {
+                        // Best-effort track version too (if enabled), not required for correctness.
+                        if (versionKey) {
+                            try {
+                                const v = await storage.getItem(versionKey);
+                                lastSavedVersion = typeof v === 'string' ? v : null;
+                                pendingSavedVersion = null;
+                            }
+                            catch {
+                                // ignore
+                            }
+                        }
+                        finalizeHydration(true);
+                        return;
+                    }
+                    let storedVersionRaw = null;
+                    if (versionKey) {
+                        const v = await storage.getItem(versionKey);
+                        storedVersionRaw = typeof v === 'string' ? v : null;
+                    }
+                    hydrateFromStored(storedValue, storedVersionRaw);
+                    finalizeHydration(false);
+                })
+                    .catch((err) => {
+                    handleError(err, 'failed to hydrate');
+                    // Even on error, allow future writes (otherwise persist becomes inert)
+                    finalizeHydration(dirtyBeforeHydrate);
+                });
+            }
+            // sync storage
+            if (stored === null) {
+                finalizeHydration(false);
+                return;
+            }
+            let storedVersionRaw = null;
+            if (versionKey) {
+                const v = storage.getItem(versionKey);
+                storedVersionRaw = isPromiseLike(v) ? null : typeof v === 'string' ? v : null;
+            }
+            hydrateFromStored(stored, storedVersionRaw);
+            finalizeHydration(false);
+        }
+        catch (err) {
+            handleError(err, 'failed to hydrate');
+            finalizeHydration(dirtyBeforeHydrate);
+        }
+    };
+    // ---- Set up persistence + dirty tracking ----
+    // Perfect dirty detection: track any changes before hydration completes.
+    // This catches even synchronous sets before the effect's first run.
+    if (!hydrated) {
+        removeDirtyListener = baseSignal.on(() => {
+            // Ignore hydration writes (hydration must NOT count as "user dirty").
+            if (!hydrated && !isHydrationWrite)
+                dirtyBeforeHydrate = true;
+        });
+    }
+    const scope = getCurrentScope();
+    if (scope) {
+        effect(() => {
+            const value = baseSignal();
+            // After hydration completes, persist normally
+            if (hydrated) {
+                persistValue(value);
+            }
+        });
+        // Clean up temporary dirty listener when scope disposes (if still active)
+        if (removeDirtyListener) {
+            scope.onCleanup(removeDirtyListener);
+        }
+    }
+    else {
+        // No scope: use manual subscription.
+        // Dirty-before-hydrate is still handled by the temporary dirty listener above.
+        baseSignal.on((value) => {
+            if (hydrated) {
+                persistValue(value);
+            }
+        });
+    }
+    // Hydrate after wiring subscribers so async hydration sets can trigger persist if needed.
+    const hydration = hydrate();
+    if (isPromiseLike(hydration)) {
+        hydration.catch((err) => {
+            // already handled inside hydrate(), but keep as last-resort safety
+            console.error(`[Dalila] persist(): hydration promise rejected for "${name}"`, err);
+        });
+    }
+    return baseSignal;
+}
+/**
+ * Helper to create JSON storage wrapper
+ */
+export function createJSONStorage(getStorage) {
+    return getStorage();
+}
+/**
+ * Clear persisted data for a given key
+ */
+export function clearPersisted(name, storage = safeDefaultStorage() ?? {}) {
+    if (!storage.removeItem) {
+        console.warn(`[Dalila] clearPersisted(): storage.removeItem not available for "${name}"`);
+        return;
+    }
+    try {
+        void storage.removeItem(name);
+        void storage.removeItem(`${name}:version`);
+    }
+    catch (err) {
+        console.error(`[Dalila] clearPersisted(): failed for "${name}"`, err);
+    }
+}
+/**
+ * Generate a minimal inline script to prevent FOUC.
+ *
+ * NOTE: Assumes the value in storage was JSON serialized (default serializer).
+ */
+export function createPreloadScript(options) {
+    const { storageKey, defaultValue, target = 'documentElement', attribute = 'data-theme', storageType = 'localStorage', } = options;
+    // Use JSON.stringify to safely embed strings (avoid breaking quotes / injection)
+    const k = JSON.stringify(storageKey);
+    const d = JSON.stringify(defaultValue);
+    const a = JSON.stringify(attribute);
+    // Still minified
+    return `(function(){try{var s=${storageType}.getItem(${k});var v=s==null?${d}:JSON.parse(s);document.${target}.setAttribute(${a},v)}catch(e){document.${target}.setAttribute(${a},${d})}})();`;
+}
+export function createThemeScript(storageKey, defaultTheme = 'light') {
+    return createPreloadScript({
+        storageKey,
+        defaultValue: defaultTheme,
+        target: 'documentElement',
+        attribute: 'data-theme',
+    });
+}

package/dist/core/scope.d.ts

@@ -55,3 +55,20 @@ export declare function setCurrentScope(scope: Scope | null): void;
  * - `effect()` can auto-dispose when the scope ends
  */
 export declare function withScope<T>(scope: Scope, fn: () => T): T;
+/**
+ * Async version of withScope that properly maintains scope during await.
+ *
+ * IMPORTANT: Use this instead of withScope when fn is async, because
+ * withScope() restores the previous scope immediately when the Promise
+ * is returned, not when it resolves. This means anything created after
+ * an await would not be in the scope.
+ *
+ * Example:
+ * ```ts
+ * await withScopeAsync(scope, async () => {
+ *   await fetch(...);
+ *   const sig = signal(0);  // ← This will be in scope
+ * });
+ * ```
+ */
+export declare function withScopeAsync<T>(scope: Scope, fn: () => Promise<T>): Promise<T>;

package/dist/core/scope.js

@@ -140,3 +140,32 @@ export function withScope(scope, fn) {
         currentScope = prevScope;
     }
 }
+/**
+ * Async version of withScope that properly maintains scope during await.
+ *
+ * IMPORTANT: Use this instead of withScope when fn is async, because
+ * withScope() restores the previous scope immediately when the Promise
+ * is returned, not when it resolves. This means anything created after
+ * an await would not be in the scope.
+ *
+ * Example:
+ * ```ts
+ * await withScopeAsync(scope, async () => {
+ *   await fetch(...);
+ *   const sig = signal(0);  // ← This will be in scope
+ * });
+ * ```
+ */
+export async function withScopeAsync(scope, fn) {
+    if (isScopeDisposed(scope)) {
+        throw new Error('[Dalila] withScopeAsync() cannot enter a disposed scope.');
+    }
+    const prevScope = currentScope;
+    currentScope = scope;
+    try {
+        return await fn();
+    }
+    finally {
+        currentScope = prevScope;
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./core/index.js";
 export * from "./context/index.js";
 export * from "./router/index.js";
-export * from "./dom/index.js";
+export * from "./runtime/index.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export * from "./core/index.js";
 export * from "./context/index.js";
 export * from "./router/index.js";
-export * from "./dom/index.js";
+export * from "./runtime/index.js";