@epoch32/visage 0.0.0 → 1.1.0

package/dist/{src/server → server}/index.js

@@ -431,10 +431,12 @@ class Signal {
   _value;
   _subscribers = new Set;
   _equals;
+  _onSet;
   version = 0;
-  constructor(initialValue, equals) {
+  constructor(initialValue, equals, onSet) {
     this._value = initialValue;
     this._equals = equals ?? Object.is;
+    this._onSet = onSet;
   }
   get() {
     if (currentSubscriber !== null && currentSubscriber.state !== 3 /* DISPOSED */) {
@@ -459,6 +461,9 @@ class Signal {
     }
     this._value = newValue;
     this.version++;
+    if (this._onSet) {
+      this._onSet(newValue);
+    }
     batch(() => {
       this.notify();
     });
@@ -484,11 +489,91 @@ class Signal {
     }
   }
 }
+function resolveStorage(storageOption) {
+  if (storageOption && typeof storageOption === "object") {
+    return storageOption;
+  }
+  if (storageOption === "session") {
+    try {
+      if (typeof sessionStorage !== "undefined")
+        return sessionStorage;
+    } catch {}
+    try {
+      if (typeof window !== "undefined" && window.sessionStorage) {
+        return window.sessionStorage;
+      }
+    } catch {}
+    try {
+      if (typeof globalThis !== "undefined" && globalThis.sessionStorage) {
+        return globalThis.sessionStorage;
+      }
+    } catch {}
+    return null;
+  }
+  try {
+    if (typeof localStorage !== "undefined")
+      return localStorage;
+  } catch {}
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage;
+    }
+  } catch {}
+  try {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {}
+  return null;
+}
 function signal(initialValue, optionsOrEquals) {
   const equals = typeof optionsOrEquals === "function" ? optionsOrEquals : optionsOrEquals?.equals;
   const isInternal = typeof optionsOrEquals === "object" ? optionsOrEquals?.internal : false;
   const customName = typeof optionsOrEquals === "object" ? optionsOrEquals?.name : undefined;
-  const s = new Signal(initialValue, equals);
+  const persistOption = typeof optionsOrEquals === "object" ? optionsOrEquals?.persist : undefined;
+  const persistConfig = persistOption ? typeof persistOption === "string" ? { key: persistOption } : persistOption : undefined;
+  let effectiveInitial = initialValue;
+  const storage = persistConfig ? resolveStorage(persistConfig.storage) : null;
+  const serialize = persistConfig?.serialize ?? JSON.stringify;
+  const deserialize = persistConfig?.deserialize ?? JSON.parse;
+  if (persistConfig && storage) {
+    try {
+      const stored = storage.getItem(persistConfig.key);
+      if (stored !== null) {
+        effectiveInitial = deserialize(stored);
+      }
+    } catch {}
+  }
+  let isSyncing = false;
+  const onSet = persistConfig && storage ? (val) => {
+    if (isSyncing)
+      return;
+    try {
+      storage.setItem(persistConfig.key, serialize(val));
+    } catch {}
+  } : undefined;
+  const s = new Signal(effectiveInitial, equals, onSet);
+  if (persistConfig && storage && (persistConfig.syncTabs ?? true) && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    const onStorage = (e) => {
+      if (e.key === persistConfig.key) {
+        try {
+          const nextVal = e.newValue !== null ? deserialize(e.newValue) : initialValue;
+          isSyncing = true;
+          try {
+            s.set(nextVal);
+          } finally {
+            isSyncing = false;
+          }
+        } catch {}
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        window.removeEventListener("storage", onStorage);
+      });
+    }
+  }
   const accessor = (...args) => {
     if (args.length === 0) {
       return s.get();

package/dist/server/render-to-stream.d.ts

@@ -0,0 +1,9 @@
+import type { Child } from "../dom/render";
+export interface StreamOptions {
+    onChunk?: (chunk: string) => void;
+    onError?: (error: any) => void;
+}
+/**
+ * Stream HTML chunks progressively using standard Web Streams (ReadableStream)
+ */
+export declare function renderToStream(fn: () => Child, options?: StreamOptions): ReadableStream<Uint8Array>;

package/dist/server/render-to-string.d.ts

@@ -0,0 +1,6 @@
+import type { Child } from "../dom/render";
+export declare function renderChildToString(child: Child): string;
+/**
+ * Synchronously render a Visage component tree to an HTML string
+ */
+export declare function renderToString(fn: () => Child): string;

package/dist/signals/computed.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Visage Lazy, Glitch-Free Computed State Engine
+ */
+import type { Scope } from "./scope";
+import { COMPUTED_BRAND, type ComputedOptions, type IDependency, type ISubscriber, type ReadonlySignal, SubscriberState } from "./types";
+export type { ComputedOptions };
+/**
+ * Computed / Derived reactive state (Lazy, Glitch-Free, Memoized)
+ */
+export declare class Computed<T> implements ISubscriber, IDependency {
+    [COMPUTED_BRAND]: true;
+    private _fn;
+    private _value;
+    private _subscribers;
+    sources: Set<IDependency>;
+    sourceVersions: Map<IDependency, number>;
+    state: SubscriberState;
+    scope: Scope | null;
+    version: number;
+    constructor(fn: () => T);
+    get(): T;
+    get value(): T;
+    removeSubscriber(sub: ISubscriber): void;
+    markDirty(targetState?: SubscriberState): void;
+    updateIfNecessary(): boolean;
+    private recompute;
+    private cleanupSources;
+    dispose(): void;
+}
+/**
+ * Factory for creating lazy, memoized, glitch-free computed signals.
+ *
+ * Computed values are only recalculated when one of their recorded reactive
+ * dependencies changes and the value is actually accessed.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(2);
+ * const double = computed(() => count() * 2);
+ *
+ * console.log(double()); // 4
+ *
+ * // In JSX, passes directly or as a function
+ * <div>Doubled value: {double}</div>
+ * ```
+ *
+ * @param fn - The pure reactive computation function
+ * @param options - Optional debug metadata and internal flags
+ * @returns A readonly reactive signal function accessor
+ */
+export declare function computed<T>(fn: () => T, options?: ComputedOptions): ReadonlySignal<T>;
+/**
+ * Solid-compatible alias for `computed()`.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(5);
+ * const squared = createMemo(() => count() ** 2);
+ * ```
+ */
+export declare const createMemo: typeof computed;

package/dist/signals/context.d.ts

@@ -0,0 +1,44 @@
+import { type Child } from "../dom/render";
+export interface Context<T> {
+    id: symbol;
+    defaultValue: T;
+    Provider: (props: {
+        value: T;
+        children: Child;
+    }) => any;
+}
+/**
+ * Create a reactive Context for dependency injection across the component tree.
+ *
+ * Context allows passing state and utilities down the component tree without
+ * manually drilling props through every intermediate component.
+ *
+ * @example
+ * ```tsx
+ * const ThemeContext = createContext<"light" | "dark">("light");
+ *
+ * // Provide value in parent
+ * function App() {
+ *   return (
+ *     <ThemeContext.Provider value="dark">
+ *       <Header />
+ *     </ThemeContext.Provider>
+ *   );
+ * }
+ *
+ * // Consume value in descendant
+ * function Header() {
+ *   const theme = useContext(ThemeContext);
+ *   return <div>Current theme: {theme}</div>;
+ * }
+ * ```
+ */
+export declare function createContext<T>(defaultValue: T): Context<T>;
+export declare function createContext<T>(): Context<T | undefined>;
+/**
+ * Consume a Context value from the nearest ancestor Provider, falling back to defaultValue.
+ *
+ * @param context - The Context object returned from `createContext`
+ * @returns The current context value
+ */
+export declare function useContext<T>(context: Context<T>): T;

package/dist/signals/effect.d.ts

@@ -0,0 +1,56 @@
+import type { Scope } from "./scope";
+import { type CleanupFn, type IDependency, type ISubscriber, SubscriberState } from "./types";
+/**
+ * Side-effect runner with automatic dependency tracking and disposal
+ */
+export declare class Effect implements ISubscriber {
+    private _fn;
+    sources: Set<IDependency>;
+    sourceVersions: Map<IDependency, number>;
+    cleanups: CleanupFn[];
+    state: SubscriberState;
+    scope: Scope | null;
+    constructor(fn: () => void | CleanupFn);
+    addCleanup(fn: CleanupFn): void;
+    private runCleanups;
+    markDirty(targetState?: SubscriberState): void;
+    run(): void;
+    private cleanupSources;
+    dispose(): void;
+}
+/**
+ * Execute side-effects reactively when dependencies change.
+ *
+ * Runs immediately upon creation and tracks any signals read within `fn`.
+ * When dependencies change, re-execution is scheduled automatically.
+ *
+ * An optional cleanup function can be returned from `fn`, which runs
+ * before the next re-execution and when the enclosing scope is disposed.
+ *
+ * @example
+ * ```tsx
+ * const count = signal(0);
+ *
+ * effect(() => {
+ *   console.log("Count changed to:", count());
+ *
+ *   const timer = setInterval(() => console.log("tick"), 1000);
+ *   return () => clearInterval(timer);
+ * });
+ * ```
+ *
+ * @param fn - The side-effect function, optionally returning a cleanup function
+ * @returns A manual disposal cleanup function
+ */
+export declare function effect(fn: () => void | CleanupFn): CleanupFn;
+/**
+ * Solid / React-compatible alias for `effect()`.
+ *
+ * @example
+ * ```tsx
+ * createEffect(() => {
+ *   document.title = `Total: ${count()}`;
+ * });
+ * ```
+ */
+export declare const createEffect: typeof effect;

package/dist/signals/index.d.ts

@@ -0,0 +1,8 @@
+export { Computed, type ComputedOptions, computed, createMemo } from "./computed";
+export { type Context, createContext, useContext } from "./context";
+export { createEffect, Effect, effect } from "./effect";
+export { createRoot, getActiveScope, onCleanup, runInScope, Scope } from "./scope";
+export { createSignal, Signal, type SignalOptions, signal } from "./signal";
+export { createStore, mutateStore, type Store, unwrapStore } from "./store";
+export { batch, untrack } from "./system";
+export { type CleanupFn, COMPUTED_BRAND, type Dependency, isSignal, type PersistOptions, type ReadonlySignal, SIGNAL_BRAND, type Subscriber, SubscriberState, type WritableSignal } from "./types";

package/dist/{src/signals → signals}/index.js

@@ -848,10 +848,12 @@ class Signal {
   _value;
   _subscribers = new Set;
   _equals;
+  _onSet;
   version = 0;
-  constructor(initialValue, equals) {
+  constructor(initialValue, equals, onSet) {
     this._value = initialValue;
     this._equals = equals ?? Object.is;
+    this._onSet = onSet;
   }
   get() {
     if (currentSubscriber !== null && currentSubscriber.state !== 3 /* DISPOSED */) {
@@ -876,6 +878,9 @@ class Signal {
     }
     this._value = newValue;
     this.version++;
+    if (this._onSet) {
+      this._onSet(newValue);
+    }
     batch(() => {
       this.notify();
     });
@@ -901,11 +906,91 @@ class Signal {
     }
   }
 }
+function resolveStorage(storageOption) {
+  if (storageOption && typeof storageOption === "object") {
+    return storageOption;
+  }
+  if (storageOption === "session") {
+    try {
+      if (typeof sessionStorage !== "undefined")
+        return sessionStorage;
+    } catch {}
+    try {
+      if (typeof window !== "undefined" && window.sessionStorage) {
+        return window.sessionStorage;
+      }
+    } catch {}
+    try {
+      if (typeof globalThis !== "undefined" && globalThis.sessionStorage) {
+        return globalThis.sessionStorage;
+      }
+    } catch {}
+    return null;
+  }
+  try {
+    if (typeof localStorage !== "undefined")
+      return localStorage;
+  } catch {}
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      return window.localStorage;
+    }
+  } catch {}
+  try {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {}
+  return null;
+}
 function signal(initialValue, optionsOrEquals) {
   const equals = typeof optionsOrEquals === "function" ? optionsOrEquals : optionsOrEquals?.equals;
   const isInternal = typeof optionsOrEquals === "object" ? optionsOrEquals?.internal : false;
   const customName = typeof optionsOrEquals === "object" ? optionsOrEquals?.name : undefined;
-  const s = new Signal(initialValue, equals);
+  const persistOption = typeof optionsOrEquals === "object" ? optionsOrEquals?.persist : undefined;
+  const persistConfig = persistOption ? typeof persistOption === "string" ? { key: persistOption } : persistOption : undefined;
+  let effectiveInitial = initialValue;
+  const storage = persistConfig ? resolveStorage(persistConfig.storage) : null;
+  const serialize = persistConfig?.serialize ?? JSON.stringify;
+  const deserialize = persistConfig?.deserialize ?? JSON.parse;
+  if (persistConfig && storage) {
+    try {
+      const stored = storage.getItem(persistConfig.key);
+      if (stored !== null) {
+        effectiveInitial = deserialize(stored);
+      }
+    } catch {}
+  }
+  let isSyncing = false;
+  const onSet = persistConfig && storage ? (val) => {
+    if (isSyncing)
+      return;
+    try {
+      storage.setItem(persistConfig.key, serialize(val));
+    } catch {}
+  } : undefined;
+  const s = new Signal(effectiveInitial, equals, onSet);
+  if (persistConfig && storage && (persistConfig.syncTabs ?? true) && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    const onStorage = (e) => {
+      if (e.key === persistConfig.key) {
+        try {
+          const nextVal = e.newValue !== null ? deserialize(e.newValue) : initialValue;
+          isSyncing = true;
+          try {
+            s.set(nextVal);
+          } finally {
+            isSyncing = false;
+          }
+        } catch {}
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    if (currentScope) {
+      currentScope.addCleanup(() => {
+        window.removeEventListener("storage", onStorage);
+      });
+    }
+  }
   const accessor = (...args) => {
     if (args.length === 0) {
       return s.get();

package/dist/signals/scope.d.ts

@@ -0,0 +1,61 @@
+import type { CleanupFn, ISubscriber } from "./types";
+/**
+ * Reactive Scope for lifecycle and automatic memory management
+ */
+export declare class Scope {
+    subscribers: Set<ISubscriber>;
+    cleanups: CleanupFn[];
+    parent: Scope | null;
+    isDisposed: boolean;
+    context?: Map<symbol, any>;
+    constructor(parent?: Scope | null);
+    addSubscriber(sub: ISubscriber): void;
+    addCleanup(fn: CleanupFn): void;
+    dispose(): void;
+}
+/**
+ * Register a cleanup callback for the current running effect or active scope.
+ *
+ * Runs automatically when the enclosing component/scope unmounts or before
+ * the effect re-executes.
+ *
+ * @example
+ * ```tsx
+ * function TimerComponent() {
+ *   const id = setInterval(() => console.log("tick"), 1000);
+ *   onCleanup(() => clearInterval(id));
+ *   return <div>Timer running</div>;
+ * }
+ * ```
+ */
+export declare function onCleanup(fn: CleanupFn): void;
+/**
+ * Create an isolated reactive root scope that outlives the current execution context.
+ *
+ * Computations and signals created inside `fn` will not be tied to any parent scope
+ * and will persist until the provided `dispose` callback is invoked.
+ *
+ * @example
+ * ```tsx
+ * const dispose = createRoot((dispose) => {
+ *   const count = signal(0);
+ *   effect(() => console.log(count()));
+ *   return dispose;
+ * });
+ *
+ * // Later, dispose of all memory & subscribers
+ * dispose();
+ * ```
+ *
+ * @param fn - A factory function receiving the `dispose` callback
+ * @returns The return value of `fn`
+ */
+export declare function createRoot<T>(fn: (dispose: () => void) => T): T;
+/**
+ * Run a function with a specified reactive scope active.
+ */
+export declare function runInScope<T>(scope: Scope | null, fn: () => T): T;
+/**
+ * Get the currently active reactive scope.
+ */
+export declare function getActiveScope(): Scope | null;

package/dist/signals/signal.d.ts

@@ -0,0 +1,40 @@
+import { type IDependency, type ISubscriber, type ReadonlySignal, SIGNAL_BRAND, type SignalOptions, type WritableSignal } from "./types";
+export type { SignalOptions };
+/**
+ * Core Writable Signal implementation
+ */
+export declare class Signal<T> implements IDependency {
+    [SIGNAL_BRAND]: true;
+    private _value;
+    private _subscribers;
+    private _equals;
+    private _onSet?;
+    version: number;
+    constructor(initialValue: T, equals?: (a: T, b: T) => boolean, onSet?: (val: T) => void);
+    get(): T;
+    set(newValue: T): void;
+    update(fn: (prev: T) => T): void;
+    get value(): T;
+    set value(val: T);
+    removeSubscriber(sub: ISubscriber): void;
+    private notify;
+}
+export declare function signal<T>(initialValue: T, optionsOrEquals?: ((a: T, b: T) => boolean) | SignalOptions<T>): WritableSignal<T>;
+/**
+ * Tuple-based signal constructor returning `[getter, setter]` (Solid / Preact Signals convention).
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = createSignal(0);
+ *
+ * setCount(5);
+ * setCount(prev => prev + 1);
+ *
+ * <div>Count: {count}</div>
+ * ```
+ *
+ * @param initialValue - The initial value stored in the signal
+ * @param optionsOrEquals - Custom equality comparison function or SignalOptions
+ * @returns A tuple containing `[ReadonlySignal<T>, (value: T | ((prev: T) => T)) => void]`
+ */
+export declare function createSignal<T>(initialValue: T, optionsOrEquals?: ((a: T, b: T) => boolean) | SignalOptions<T>): [ReadonlySignal<T>, (value: T | ((prev: T) => T)) => void];

package/dist/signals/store.d.ts

@@ -0,0 +1,45 @@
+export type Store<T> = T;
+/**
+ * Create a deep reactive proxy store with per-property fine-grained signal tracking.
+ *
+ * Nested objects and arrays are lazily wrapped in reactive proxies. Reading a property
+ * tracks that exact key, and updating a property only notifies computations observing that key.
+ *
+ * @example
+ * ```tsx
+ * const state = createStore({
+ *   user: { name: "Alice", role: "admin" },
+ *   items: ["Apple", "Banana"]
+ * });
+ *
+ * // Fine-grained read
+ * <div>User: {() => state.user.name}</div>
+ *
+ * // Fine-grained write (mutates only user.name subscribers)
+ * state.user.name = "Bob";
+ * state.items.push("Cherry");
+ * ```
+ *
+ * @param initialState - An object or array representing the initial state tree
+ * @returns A deeply reactive proxy store
+ */
+export declare function createStore<T extends object>(initialState: T): Store<T>;
+/**
+ * Mutate a store inside a synchronous batch operation.
+ *
+ * @example
+ * ```tsx
+ * mutateStore(state, (draft) => {
+ *   draft.user.name = "Charlie";
+ *   draft.user.role = "user";
+ * });
+ * ```
+ */
+export declare function mutateStore<T extends object>(store: Store<T>, mutator: (draft: T) => void): void;
+/**
+ * Unwrap a reactive proxy store to get the underlying raw, un-proxied JavaScript object.
+ *
+ * @param store - The reactive store proxy
+ * @returns The raw underlying object
+ */
+export declare function unwrapStore<T>(store: T): T;

package/dist/signals/system.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Visage Reactivity System Execution Context & Scheduler
+ */
+import { type ISubscriber } from "./types";
+export declare let currentSubscriber: ISubscriber | null;
+export declare let currentScope: any;
+export declare let batchDepth: number;
+export declare const pendingEffects: Set<any>;
+export declare const warnedCyclicSubscribers: WeakSet<ISubscriber>;
+export declare let isFlushing: boolean;
+export declare function setCurrentSubscriber(sub: ISubscriber | null): void;
+export declare function getCurrentSubscriber(): ISubscriber | null;
+export declare function setCurrentScope(scope: any): void;
+export declare function getCurrentScope(): any;
+export declare function addPendingEffect(eff: any): void;
+export declare function removePendingEffect(eff: any): void;
+export declare function flushEffects(): void;
+/**
+ * Batch multiple signal mutations so downstreams and effects update synchronously once at completion.
+ *
+ * Prevents intermediate flicker, wasted recomputations, and glitch states.
+ *
+ * @example
+ * ```tsx
+ * const firstName = signal("Jane");
+ * const lastName = signal("Doe");
+ *
+ * batch(() => {
+ *   firstName.set("John");
+ *   lastName.set("Smith");
+ *   // Downstream computed and effects run only ONCE here
+ * });
+ * ```
+ *
+ * @param fn - A function performing multiple signal updates
+ * @returns The return value of `fn`
+ */
+export declare function batch<T>(fn: () => T): T;
+/**
+ * Read reactive state without subscribing the current active effect or computed computation.
+ *
+ * @example
+ * ```tsx
+ * effect(() => {
+ *   const id = currentId(); // Subscribed: effect re-runs when currentId changes
+ *
+ *   // Not subscribed: effect does NOT re-run when analyticsCounter changes
+ *   const count = untrack(() => analyticsCounter());
+ *   sendMetric(id, count);
+ * });
+ * ```
+ *
+ * @param fn - A function reading reactive signals without tracking
+ * @returns The return value of `fn`
+ */
+export declare function untrack<T>(fn: () => T): T;

package/dist/signals/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Visage Fine-Grained Reactive Engine Type Definitions
+ */
+export type CleanupFn = () => void;
+export declare enum SubscriberState {
+    CLEAN = 0,
+    CHECK_DIRTY = 1,
+    DIRTY = 2,
+    DISPOSED = 3
+}
+export declare const SIGNAL_BRAND: unique symbol;
+export declare const COMPUTED_BRAND: unique symbol;
+export interface ReadonlySignal<T> {
+    get(): T;
+    readonly value: T;
+    (): T;
+    readonly [SIGNAL_BRAND]: true;
+}
+export interface WritableSignal<T> extends ReadonlySignal<T> {
+    set(value: T): void;
+    update(fn: (prev: T) => T): void;
+    (value?: T): T;
+    value: T;
+}
+export interface PersistOptions<T> {
+    key: string;
+    storage?: "local" | "session" | Storage;
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    syncTabs?: boolean;
+}
+export interface SignalOptions<T> {
+    name?: string;
+    equals?: (a: T, b: T) => boolean;
+    internal?: boolean;
+    persist?: string | PersistOptions<T>;
+}
+export interface ComputedOptions {
+    name?: string;
+    internal?: boolean;
+}
+/**
+ * Check if a value is a Visage signal or computed
+ */
+export declare function isSignal<T = unknown>(value: unknown): value is ReadonlySignal<T>;
+export interface ISubscriber {
+    state: SubscriberState;
+    sources: Set<IDependency>;
+    sourceVersions: Map<IDependency, number>;
+    markDirty(targetState?: SubscriberState): void;
+    dispose(): void;
+}
+export interface IDependency {
+    version: number;
+    removeSubscriber(sub: ISubscriber): void;
+}
+export type Subscriber = ISubscriber;
+export type Dependency = IDependency;