sibujs 1.3.0 → 1.5.0

package/dist/index.d.cts

@@ -319,14 +319,12 @@ declare function each<T>(getArray: () => T[], render: (item: () => T, index: ()
  *
  * @example
  * ```ts
- * div({
- *   nodes: [
- *     Fragment([
- *       p({ nodes: "First" }),
- *       p({ nodes: "Second" }),
- *     ])
- *   ]
- * });
+ * div([
+ *   Fragment([
+ *     p("First"),
+ *     p("Second"),
+ *   ])
+ * ]);
  * ```
  *
  * @param nodes Array of child nodes to include in the fragment
@@ -338,6 +336,10 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * Portal renders nodes into a DOM node outside the parent component hierarchy.
  * Useful for modals, tooltips, dropdowns, and overlays.
  *
+ * Cleanup integrates with `dispose()` / `registerDisposer()` so portals
+ * are properly torn down when the anchor is disposed by `when()`, `match()`,
+ * `each()`, or manual `dispose(anchor)`.
+ *
  * @param nodes Function that returns the content to render
  * @param target Target DOM element (defaults to document.body)
  * @returns A Comment anchor node in the original position
@@ -345,11 +347,11 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * @example
  * ```ts
  * // Render modal at document.body
- * Portal(() => div({ class: "modal", nodes: "Modal content" }));
+ * Portal(() => div("modal", "Modal content"));
  *
  * // Render into specific container
  * const overlay = document.getElementById("overlay-root")!;
- * Portal(() => div({ nodes: "Tooltip" }), overlay);
+ * Portal(() => div("Tooltip"), overlay);
  * ```
  */
 declare function Portal(nodes: () => HTMLElement, target?: HTMLElement): Comment;
@@ -382,7 +384,7 @@ declare function unregisterComponent(name: string): void;
  * @example
  * ```ts
  * registerComponent("Widget", MyWidget);
- * div({ nodes: [resolveComponent("Widget")] });
+ * div([resolveComponent("Widget")]);
  * ```
  */
 declare function resolveComponent(name: string): HTMLElement;
@@ -418,7 +420,7 @@ declare function getSlot(slots: Slots | undefined, name?: string): SlotFn | unde
  * @example
  * ```ts
  * const [visible, setVisible] = signal(true);
- * div({ nodes: [show(() => visible(), span({ nodes: "I toggle!" }))] });
+ * div([show(() => visible(), span("I toggle!"))]);
  * ```
  */
 declare function show<T extends Element>(condition: () => boolean, element: T): T;
@@ -435,8 +437,8 @@ declare function show<T extends Element>(condition: () => boolean, element: T):
  * ```ts
  * when(
  *   () => isLoggedIn(),
- *   () => div({ nodes: "Welcome!" }),
- *   () => div({ nodes: "Please log in" })
+ *   () => div("Welcome!"),
+ *   () => div("Please log in")
  * );
  * ```
  */
@@ -459,7 +461,7 @@ declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBr
  *     error: () => ErrorMessage(),
  *     success: () => Content(),
  *   },
- *   () => div({ nodes: "Unknown status" })
+ *   () => div("Unknown status")
  * );
  * ```
  */
@@ -527,8 +529,7 @@ type ActionFn<T = void> = (element: HTMLElement, param: T) => (() => void) | und
  *     action(el, clickOutside, () => setOpen(false));
  *     action(el, longPress, { duration: 500, callback: onLongPress });
  *   },
- *   nodes: "Content",
- * });
+ * }, "Content");
  * ```
  */
 declare function action<T>(element: HTMLElement, actionFn: ActionFn<T>, param: T): void;
@@ -636,10 +637,10 @@ declare function setGlobalErrorHandler(handler: ErrorHandler): void;
  * ```ts
  * function Field(labelText: string) {
  *   const id = createId("field");
- *   return div({ nodes: [
- *     label({ for: id, nodes: labelText }),
+ *   return div([
+ *     label({ for: id }, labelText),
  *     input({ id }),
- *   ]});
+ *   ]);
  * }
  * ```
  */
@@ -675,15 +676,15 @@ declare function checkLeaks(warnThreshold?: number): number;
 
 declare const __accessor: unique symbol;
 /**
- * A reactive signal getter returned by signal(), derived(), memo(), and similar primitives.
+ * A reactive signal getter returned by signal(), derived(), and similar primitives.
  *
  * Pass an Accessor directly into reactive prop positions — never call it there:
  * ```ts
  * const [count, setCount] = signal(0);
  *
- * div({ nodes: count })           // ✓ reactive — Accessor passed directly
- * div({ nodes: () => count() })   // ✓ reactive — explicit arrow wrapper
- * div({ nodes: count() })         // ✗ static  — evaluated once, not reactive
+ * div(count)                       // ✓ reactive — Accessor passed directly
+ * div(() => count())               // ✓ reactive — explicit arrow wrapper
+ * div(count())                     // ✗ static  — evaluated once, not reactive
  * ```
  */
 type Accessor<T> = (() => T) & {
@@ -828,28 +829,6 @@ interface Ref<T> {
 declare function ref<T>(initial: T): Ref<T>;
 declare function ref<T = undefined>(): Ref<T | undefined>;
 
-/**
- * memo returns a memoized value that only recomputes when its
- * reactive dependencies change. This is semantically identical to
- * derived but named for convenience.
- *
- * Use this to avoid expensive computations on every render cycle.
- *
- * @param factory Function that computes the memoized value
- * @returns Getter function that returns the memoized value
- */
-declare function memo<T>(factory: () => T): Accessor<T>;
-
-/**
- * memoFn returns a memoized callback function that only updates
- * when its reactive dependencies change. This prevents unnecessary
- * re-creations of callback functions passed to child components.
- *
- * @param callback The callback function to memoize
- * @returns Getter that returns the current memoized callback
- */
-declare function memoFn<T extends (...args: any[]) => any>(callback: () => T): Accessor<T>;
-
 /**
  * Reactive array hook. Provides common array operations that
  * automatically trigger reactive updates.
@@ -925,16 +904,23 @@ declare function reactiveArray<T>(initial?: T[]): [Accessor<readonly T[]>, Array
 /**
  * Deep equality comparison for objects and arrays.
  * Falls back to Object.is for primitives.
- * Handles circular references and common built-in types (Date, RegExp).
+ * Handles circular references, shared sub-references, and common
+ * built-in types (Date, RegExp, Map, Set, ArrayBuffer, TypedArrays).
+ *
+ * The `seen` parameter tracks `(a, b)` pairs — not just `a` — so that
+ * a shared sub-object compared against two different partners is always
+ * fully checked, while genuine cycles (same a-with-same-b revisited)
+ * still terminate.
  */
-declare function deepEqual(a: unknown, b: unknown, seen?: Set<unknown>): boolean;
+declare function deepEqual(a: unknown, b: unknown, seen?: Map<object, Set<object>>): boolean;
 /**
  * Like signal but uses deep equality comparison instead of Object.is.
  * This prevents unnecessary re-renders when setting an object/array
  * to a structurally identical value.
  *
  * @param initial Initial value
- * @returns Tuple [getter, setter]
+ * @returns Tuple [getter, setter] — same shape as `signal()`, preserving
+ *          the `Accessor<T>` brand on the getter.
  *
  * @example
  * ```ts
@@ -943,7 +929,7 @@ declare function deepEqual(a: unknown, b: unknown, seen?: Set<unknown>): boolean
  * setUser({ name: "Bob", age: 25 });   // Notifies — different value
  * ```
  */
-declare function deepSignal<T>(initial: T): [() => T, (next: T | ((prev: T) => T)) => void];
+declare function deepSignal<T>(initial: T): [Accessor<T>, (next: T | ((prev: T) => T)) => void];
 
 /**
  * Creates a writable computed value — a derived getter paired with
@@ -1039,7 +1025,7 @@ declare function asyncDerived<T>(factory: () => Promise<T>, initial: T): AsyncDe
  *     console.log("Component was removed");
  *   });
  *
- *   return div({ nodes: "Hello" });
+ *   return div("Hello");
  * }
  * ```
  */
@@ -1076,7 +1062,7 @@ declare function onUnmount(callback: CleanupFn, element: HTMLElement): void;
  * ```ts
  * function RealtimeBar(siteId: string) {
  *   const ws = new WebSocket(`/ws/sites/${siteId}/realtime`);
- *   const root = div({ nodes: "Realtime data..." });
+ *   const root = div("Realtime data...");
  *   onCleanup(() => ws.close(), root);
  *   return root;
  * }
@@ -1085,29 +1071,31 @@ declare function onUnmount(callback: CleanupFn, element: HTMLElement): void;
 declare function onCleanup(callback: CleanupFn, element: Node): void;
 
 /**
- * Context API for SibuJS — provides dependency injection across
- * component trees without prop drilling.
+ * Context API for SibuJS — a reactive global value that any component
+ * can read without prop drilling.
+ *
+ * Note: this is a **global reactive store**, not a subtree-scoped DI
+ * system. Calling `provide()` sets the value for ALL consumers, not
+ * just descendants of the provider. For most apps this is sufficient
+ * — use separate `context()` instances for independent scopes.
  *
  * @example
  * ```ts
  * // Create a context with a default value
  * const ThemeContext = context("light");
  *
- * // Provide a value at a parent level
- * function App() {
- *   ThemeContext.provide("dark");
- *   return div({ nodes: [Child()] });
- * }
+ * // Set the value (global — affects all consumers)
+ * ThemeContext.provide("dark");
  *
- * // Consume the value anywhere below
+ * // Read reactively from any component
  * function Child() {
  *   const theme = ThemeContext.use(); // reactive getter
- *   return div({ nodes: () => `Theme: ${theme()}` });
+ *   return div(() => `Theme: ${theme()}`);
  * }
  * ```
  */
 interface Context<T> {
-    /** Provide a value for this context. Overrides any parent provider. */
+    /** Set the context value globally. Affects all consumers. */
     provide(value: T): void;
     /** Get a reactive getter for the current context value. */
     use(): () => T;
@@ -1265,7 +1253,7 @@ declare function nextTick(): Promise<void>;
  * input({ on: { input: e => setQuery(e.target.value) } });
  *
  * // heavy list reads deferredQuery() and updates one frame later
- * each(() => heavyFilter(items, deferredQuery()), row => li({ nodes: row.name }));
+ * each(() => heavyFilter(items, deferredQuery()), row => li(row.name));
  * ```
  */
 declare function defer<T>(getter: () => T): () => T;
@@ -1334,7 +1322,7 @@ type LazyImport = () => Promise<{
  * // Use inside Suspense for custom loading UI
  * Suspense({
  *   nodes: () => LazyDashboard(),
- *   fallback: () => div({ nodes: "Loading dashboard..." }),
+ *   fallback: () => div("Loading dashboard..."),
  * });
  *
  * // Or use standalone — shows default "Loading..." text
@@ -1352,7 +1340,7 @@ declare function lazy(importFn: LazyImport): Component;
  * ```ts
  * Suspense({
  *   nodes: () => LazyChart(),
- *   fallback: () => div({ nodes: "Loading chart..." }),
+ *   fallback: () => div("Loading chart..."),
  * });
  * ```
  *
@@ -1392,7 +1380,7 @@ interface ErrorBoundaryProps {
      * const [route, setRoute] = signal("/");
      * ErrorBoundary({
      *   resetKeys: [route],
-     *   nodes: () => div({ nodes: riskyPageFor(route()) }),
+     *   nodes: () => div(riskyPageFor(route())),
      * });
      * ```
      */
@@ -1451,13 +1439,13 @@ interface ErrorDisplayProps {
  *
  * @example
  * ```ts
- * button({
- *   on: { click: async () => {
+ * button(
+ *   { on: { click: async () => {
  *     try { await save(); }
  *     catch (err) { mount(ErrorDisplay({ error: err, onRetry: save }), errorHost); }
- *   }},
- *   nodes: "Save",
- * });
+ *   }}},
+ *   "Save",
+ * );
  * ```
  */
 declare function ErrorDisplay(props: ErrorDisplayProps): Element;
@@ -1483,4 +1471,4 @@ interface LoadingProps {
  */
 declare function Loading(props?: LoadingProps): HTMLElement;
 
-export { type Accessor, type ActionFn, type AnchorProps, type ArrayActions, type AsyncDerivedState, type AudioProps, type ButtonProps, type Context, DynamicComponent, type EffectOptions, ErrorBoundary, type ErrorBoundaryProps, ErrorDisplay, type ErrorDisplayProps, type ErrorSeverity, type FormProps, Fragment, type ImgProps, type InputProps, type InputType, KeepAlive, type KeepAliveOptions, type LabelProps, Loading, type LoadingProps, type LongPressOptions, type MediaProps, NodeChild, NodeChildren, type OptionProps, Portal, type Ref, type SelectProps, type SignalOptions, type SlotFn, type Slots, type StoreActions, Suspense, type SuspenseProps, TagProps, type TextareaProps, type TypedTagFunction, type VideoProps, __resetIdCounter, a, abbr, action, address, area, array, article, aside, asyncDerived, audio, autoResize, b, base, batch, bdi, bdo, bindDynamic, blockquote, body, br, button, canvas, caption, catchError, catchErrorAsync, center, checkLeaks, circle, cite, clickOutside, clipPath, code, col, colgroup, context, copyOnClick, createId, customElement, data, datalist, dd, deepEqual, deepSignal, defer, defs, del, derived, details, dfn, dialog, disableSSR, dispose, div, dl, dt, each, effect, ellipse, em, embed, enableSSR, enqueueBatchedSignal, fieldset, figcaption, figure, font, footer, form, g, getSlot, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, iframe, img, input, ins, isBatching, isSSR, kbd, label, lazy, legend, li, line, linearGradient, link, longPress, main, map, mark, marker, marquee, mask, match, math, memo, memoFn, menu, meta, meter, mount, nav, nextTick, noscript, object, ol, on, onCleanup, onMount, onUnmount, optgroup, option, output, p, param, path, pattern, picture, polygon, polyline, portal, pre, progress, q, radialGradient, reactiveArray, rect, ref, registerComponent, registerDisposer, resolveComponent, rp, rt, ruby, s, samp, script, section, select, setGlobalErrorHandler, show, signal, slot, small, source, span, stop, store, strict, strictEffect, strong, style, sub, summary, sup, svg, symbol, table, tbody, td, template, text, textarea, tfoot, th, thead, time, title, tr, track, transition, trapFocus, tspan, u, ul, unregisterComponent, untracked, use, var_, video, watch, when, withSSR, writable };
+export { type Accessor, type ActionFn, type AnchorProps, type ArrayActions, type AsyncDerivedState, type AudioProps, type ButtonProps, type Context, DynamicComponent, type EffectOptions, ErrorBoundary, type ErrorBoundaryProps, ErrorDisplay, type ErrorDisplayProps, type ErrorSeverity, type FormProps, Fragment, type ImgProps, type InputProps, type InputType, KeepAlive, type KeepAliveOptions, type LabelProps, Loading, type LoadingProps, type LongPressOptions, type MediaProps, NodeChild, NodeChildren, type OptionProps, Portal, type Ref, type SelectProps, type SignalOptions, type SlotFn, type Slots, type StoreActions, Suspense, type SuspenseProps, TagProps, type TextareaProps, type TypedTagFunction, type VideoProps, __resetIdCounter, a, abbr, action, address, area, array, article, aside, asyncDerived, audio, autoResize, b, base, batch, bdi, bdo, bindDynamic, blockquote, body, br, button, canvas, caption, catchError, catchErrorAsync, center, checkLeaks, circle, cite, clickOutside, clipPath, code, col, colgroup, context, copyOnClick, createId, customElement, data, datalist, dd, deepEqual, deepSignal, defer, defs, del, derived, details, dfn, dialog, disableSSR, dispose, div, dl, dt, each, effect, ellipse, em, embed, enableSSR, enqueueBatchedSignal, fieldset, figcaption, figure, font, footer, form, g, getSlot, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, iframe, img, input, ins, isBatching, isSSR, kbd, label, lazy, legend, li, line, linearGradient, link, longPress, main, map, mark, marker, marquee, mask, match, math, menu, meta, meter, mount, nav, nextTick, noscript, object, ol, on, onCleanup, onMount, onUnmount, optgroup, option, output, p, param, path, pattern, picture, polygon, polyline, portal, pre, progress, q, radialGradient, reactiveArray, rect, ref, registerComponent, registerDisposer, resolveComponent, rp, rt, ruby, s, samp, script, section, select, setGlobalErrorHandler, show, signal, slot, small, source, span, stop, store, strict, strictEffect, strong, style, sub, summary, sup, svg, symbol, table, tbody, td, template, text, textarea, tfoot, th, thead, time, title, tr, track, transition, trapFocus, tspan, u, ul, unregisterComponent, untracked, use, var_, video, watch, when, withSSR, writable };

package/dist/index.d.ts

@@ -319,14 +319,12 @@ declare function each<T>(getArray: () => T[], render: (item: () => T, index: ()
  *
  * @example
  * ```ts
- * div({
- *   nodes: [
- *     Fragment([
- *       p({ nodes: "First" }),
- *       p({ nodes: "Second" }),
- *     ])
- *   ]
- * });
+ * div([
+ *   Fragment([
+ *     p("First"),
+ *     p("Second"),
+ *   ])
+ * ]);
  * ```
  *
  * @param nodes Array of child nodes to include in the fragment
@@ -338,6 +336,10 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * Portal renders nodes into a DOM node outside the parent component hierarchy.
  * Useful for modals, tooltips, dropdowns, and overlays.
  *
+ * Cleanup integrates with `dispose()` / `registerDisposer()` so portals
+ * are properly torn down when the anchor is disposed by `when()`, `match()`,
+ * `each()`, or manual `dispose(anchor)`.
+ *
  * @param nodes Function that returns the content to render
  * @param target Target DOM element (defaults to document.body)
  * @returns A Comment anchor node in the original position
@@ -345,11 +347,11 @@ declare function Fragment(nodes: NodeChildren[]): DocumentFragment;
  * @example
  * ```ts
  * // Render modal at document.body
- * Portal(() => div({ class: "modal", nodes: "Modal content" }));
+ * Portal(() => div("modal", "Modal content"));
  *
  * // Render into specific container
  * const overlay = document.getElementById("overlay-root")!;
- * Portal(() => div({ nodes: "Tooltip" }), overlay);
+ * Portal(() => div("Tooltip"), overlay);
  * ```
  */
 declare function Portal(nodes: () => HTMLElement, target?: HTMLElement): Comment;
@@ -382,7 +384,7 @@ declare function unregisterComponent(name: string): void;
  * @example
  * ```ts
  * registerComponent("Widget", MyWidget);
- * div({ nodes: [resolveComponent("Widget")] });
+ * div([resolveComponent("Widget")]);
  * ```
  */
 declare function resolveComponent(name: string): HTMLElement;
@@ -418,7 +420,7 @@ declare function getSlot(slots: Slots | undefined, name?: string): SlotFn | unde
  * @example
  * ```ts
  * const [visible, setVisible] = signal(true);
- * div({ nodes: [show(() => visible(), span({ nodes: "I toggle!" }))] });
+ * div([show(() => visible(), span("I toggle!"))]);
  * ```
  */
 declare function show<T extends Element>(condition: () => boolean, element: T): T;
@@ -435,8 +437,8 @@ declare function show<T extends Element>(condition: () => boolean, element: T):
  * ```ts
  * when(
  *   () => isLoggedIn(),
- *   () => div({ nodes: "Welcome!" }),
- *   () => div({ nodes: "Please log in" })
+ *   () => div("Welcome!"),
+ *   () => div("Please log in")
  * );
  * ```
  */
@@ -459,7 +461,7 @@ declare function when<T>(condition: () => T, thenBranch: () => NodeChild, elseBr
  *     error: () => ErrorMessage(),
  *     success: () => Content(),
  *   },
- *   () => div({ nodes: "Unknown status" })
+ *   () => div("Unknown status")
  * );
  * ```
  */
@@ -527,8 +529,7 @@ type ActionFn<T = void> = (element: HTMLElement, param: T) => (() => void) | und
  *     action(el, clickOutside, () => setOpen(false));
  *     action(el, longPress, { duration: 500, callback: onLongPress });
  *   },
- *   nodes: "Content",
- * });
+ * }, "Content");
  * ```
  */
 declare function action<T>(element: HTMLElement, actionFn: ActionFn<T>, param: T): void;
@@ -636,10 +637,10 @@ declare function setGlobalErrorHandler(handler: ErrorHandler): void;
  * ```ts
  * function Field(labelText: string) {
  *   const id = createId("field");
- *   return div({ nodes: [
- *     label({ for: id, nodes: labelText }),
+ *   return div([
+ *     label({ for: id }, labelText),
  *     input({ id }),
- *   ]});
+ *   ]);
  * }
  * ```
  */
@@ -675,15 +676,15 @@ declare function checkLeaks(warnThreshold?: number): number;
 
 declare const __accessor: unique symbol;
 /**
- * A reactive signal getter returned by signal(), derived(), memo(), and similar primitives.
+ * A reactive signal getter returned by signal(), derived(), and similar primitives.
  *
  * Pass an Accessor directly into reactive prop positions — never call it there:
  * ```ts
  * const [count, setCount] = signal(0);
  *
- * div({ nodes: count })           // ✓ reactive — Accessor passed directly
- * div({ nodes: () => count() })   // ✓ reactive — explicit arrow wrapper
- * div({ nodes: count() })         // ✗ static  — evaluated once, not reactive
+ * div(count)                       // ✓ reactive — Accessor passed directly
+ * div(() => count())               // ✓ reactive — explicit arrow wrapper
+ * div(count())                     // ✗ static  — evaluated once, not reactive
  * ```
  */
 type Accessor<T> = (() => T) & {
@@ -828,28 +829,6 @@ interface Ref<T> {
 declare function ref<T>(initial: T): Ref<T>;
 declare function ref<T = undefined>(): Ref<T | undefined>;
 
-/**
- * memo returns a memoized value that only recomputes when its
- * reactive dependencies change. This is semantically identical to
- * derived but named for convenience.
- *
- * Use this to avoid expensive computations on every render cycle.
- *
- * @param factory Function that computes the memoized value
- * @returns Getter function that returns the memoized value
- */
-declare function memo<T>(factory: () => T): Accessor<T>;
-
-/**
- * memoFn returns a memoized callback function that only updates
- * when its reactive dependencies change. This prevents unnecessary
- * re-creations of callback functions passed to child components.
- *
- * @param callback The callback function to memoize
- * @returns Getter that returns the current memoized callback
- */
-declare function memoFn<T extends (...args: any[]) => any>(callback: () => T): Accessor<T>;
-
 /**
  * Reactive array hook. Provides common array operations that
  * automatically trigger reactive updates.
@@ -925,16 +904,23 @@ declare function reactiveArray<T>(initial?: T[]): [Accessor<readonly T[]>, Array
 /**
  * Deep equality comparison for objects and arrays.
  * Falls back to Object.is for primitives.
- * Handles circular references and common built-in types (Date, RegExp).
+ * Handles circular references, shared sub-references, and common
+ * built-in types (Date, RegExp, Map, Set, ArrayBuffer, TypedArrays).
+ *
+ * The `seen` parameter tracks `(a, b)` pairs — not just `a` — so that
+ * a shared sub-object compared against two different partners is always
+ * fully checked, while genuine cycles (same a-with-same-b revisited)
+ * still terminate.
  */
-declare function deepEqual(a: unknown, b: unknown, seen?: Set<unknown>): boolean;
+declare function deepEqual(a: unknown, b: unknown, seen?: Map<object, Set<object>>): boolean;
 /**
  * Like signal but uses deep equality comparison instead of Object.is.
  * This prevents unnecessary re-renders when setting an object/array
  * to a structurally identical value.
  *
  * @param initial Initial value
- * @returns Tuple [getter, setter]
+ * @returns Tuple [getter, setter] — same shape as `signal()`, preserving
+ *          the `Accessor<T>` brand on the getter.
  *
  * @example
  * ```ts
@@ -943,7 +929,7 @@ declare function deepEqual(a: unknown, b: unknown, seen?: Set<unknown>): boolean
  * setUser({ name: "Bob", age: 25 });   // Notifies — different value
  * ```
  */
-declare function deepSignal<T>(initial: T): [() => T, (next: T | ((prev: T) => T)) => void];
+declare function deepSignal<T>(initial: T): [Accessor<T>, (next: T | ((prev: T) => T)) => void];
 
 /**
  * Creates a writable computed value — a derived getter paired with
@@ -1039,7 +1025,7 @@ declare function asyncDerived<T>(factory: () => Promise<T>, initial: T): AsyncDe
  *     console.log("Component was removed");
  *   });
  *
- *   return div({ nodes: "Hello" });
+ *   return div("Hello");
  * }
  * ```
  */
@@ -1076,7 +1062,7 @@ declare function onUnmount(callback: CleanupFn, element: HTMLElement): void;
  * ```ts
  * function RealtimeBar(siteId: string) {
  *   const ws = new WebSocket(`/ws/sites/${siteId}/realtime`);
- *   const root = div({ nodes: "Realtime data..." });
+ *   const root = div("Realtime data...");
  *   onCleanup(() => ws.close(), root);
  *   return root;
  * }
@@ -1085,29 +1071,31 @@ declare function onUnmount(callback: CleanupFn, element: HTMLElement): void;
 declare function onCleanup(callback: CleanupFn, element: Node): void;
 
 /**
- * Context API for SibuJS — provides dependency injection across
- * component trees without prop drilling.
+ * Context API for SibuJS — a reactive global value that any component
+ * can read without prop drilling.
+ *
+ * Note: this is a **global reactive store**, not a subtree-scoped DI
+ * system. Calling `provide()` sets the value for ALL consumers, not
+ * just descendants of the provider. For most apps this is sufficient
+ * — use separate `context()` instances for independent scopes.
  *
  * @example
  * ```ts
  * // Create a context with a default value
  * const ThemeContext = context("light");
  *
- * // Provide a value at a parent level
- * function App() {
- *   ThemeContext.provide("dark");
- *   return div({ nodes: [Child()] });
- * }
+ * // Set the value (global — affects all consumers)
+ * ThemeContext.provide("dark");
  *
- * // Consume the value anywhere below
+ * // Read reactively from any component
  * function Child() {
  *   const theme = ThemeContext.use(); // reactive getter
- *   return div({ nodes: () => `Theme: ${theme()}` });
+ *   return div(() => `Theme: ${theme()}`);
  * }
  * ```
  */
 interface Context<T> {
-    /** Provide a value for this context. Overrides any parent provider. */
+    /** Set the context value globally. Affects all consumers. */
     provide(value: T): void;
     /** Get a reactive getter for the current context value. */
     use(): () => T;
@@ -1265,7 +1253,7 @@ declare function nextTick(): Promise<void>;
  * input({ on: { input: e => setQuery(e.target.value) } });
  *
  * // heavy list reads deferredQuery() and updates one frame later
- * each(() => heavyFilter(items, deferredQuery()), row => li({ nodes: row.name }));
+ * each(() => heavyFilter(items, deferredQuery()), row => li(row.name));
  * ```
  */
 declare function defer<T>(getter: () => T): () => T;
@@ -1334,7 +1322,7 @@ type LazyImport = () => Promise<{
  * // Use inside Suspense for custom loading UI
  * Suspense({
  *   nodes: () => LazyDashboard(),
- *   fallback: () => div({ nodes: "Loading dashboard..." }),
+ *   fallback: () => div("Loading dashboard..."),
  * });
  *
  * // Or use standalone — shows default "Loading..." text
@@ -1352,7 +1340,7 @@ declare function lazy(importFn: LazyImport): Component;
  * ```ts
  * Suspense({
  *   nodes: () => LazyChart(),
- *   fallback: () => div({ nodes: "Loading chart..." }),
+ *   fallback: () => div("Loading chart..."),
  * });
  * ```
  *
@@ -1392,7 +1380,7 @@ interface ErrorBoundaryProps {
      * const [route, setRoute] = signal("/");
      * ErrorBoundary({
      *   resetKeys: [route],
-     *   nodes: () => div({ nodes: riskyPageFor(route()) }),
+     *   nodes: () => div(riskyPageFor(route())),
      * });
      * ```
      */
@@ -1451,13 +1439,13 @@ interface ErrorDisplayProps {
  *
  * @example
  * ```ts
- * button({
- *   on: { click: async () => {
+ * button(
+ *   { on: { click: async () => {
  *     try { await save(); }
  *     catch (err) { mount(ErrorDisplay({ error: err, onRetry: save }), errorHost); }
- *   }},
- *   nodes: "Save",
- * });
+ *   }}},
+ *   "Save",
+ * );
  * ```
  */
 declare function ErrorDisplay(props: ErrorDisplayProps): Element;
@@ -1483,4 +1471,4 @@ interface LoadingProps {
  */
 declare function Loading(props?: LoadingProps): HTMLElement;
 
-export { type Accessor, type ActionFn, type AnchorProps, type ArrayActions, type AsyncDerivedState, type AudioProps, type ButtonProps, type Context, DynamicComponent, type EffectOptions, ErrorBoundary, type ErrorBoundaryProps, ErrorDisplay, type ErrorDisplayProps, type ErrorSeverity, type FormProps, Fragment, type ImgProps, type InputProps, type InputType, KeepAlive, type KeepAliveOptions, type LabelProps, Loading, type LoadingProps, type LongPressOptions, type MediaProps, NodeChild, NodeChildren, type OptionProps, Portal, type Ref, type SelectProps, type SignalOptions, type SlotFn, type Slots, type StoreActions, Suspense, type SuspenseProps, TagProps, type TextareaProps, type TypedTagFunction, type VideoProps, __resetIdCounter, a, abbr, action, address, area, array, article, aside, asyncDerived, audio, autoResize, b, base, batch, bdi, bdo, bindDynamic, blockquote, body, br, button, canvas, caption, catchError, catchErrorAsync, center, checkLeaks, circle, cite, clickOutside, clipPath, code, col, colgroup, context, copyOnClick, createId, customElement, data, datalist, dd, deepEqual, deepSignal, defer, defs, del, derived, details, dfn, dialog, disableSSR, dispose, div, dl, dt, each, effect, ellipse, em, embed, enableSSR, enqueueBatchedSignal, fieldset, figcaption, figure, font, footer, form, g, getSlot, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, iframe, img, input, ins, isBatching, isSSR, kbd, label, lazy, legend, li, line, linearGradient, link, longPress, main, map, mark, marker, marquee, mask, match, math, memo, memoFn, menu, meta, meter, mount, nav, nextTick, noscript, object, ol, on, onCleanup, onMount, onUnmount, optgroup, option, output, p, param, path, pattern, picture, polygon, polyline, portal, pre, progress, q, radialGradient, reactiveArray, rect, ref, registerComponent, registerDisposer, resolveComponent, rp, rt, ruby, s, samp, script, section, select, setGlobalErrorHandler, show, signal, slot, small, source, span, stop, store, strict, strictEffect, strong, style, sub, summary, sup, svg, symbol, table, tbody, td, template, text, textarea, tfoot, th, thead, time, title, tr, track, transition, trapFocus, tspan, u, ul, unregisterComponent, untracked, use, var_, video, watch, when, withSSR, writable };
+export { type Accessor, type ActionFn, type AnchorProps, type ArrayActions, type AsyncDerivedState, type AudioProps, type ButtonProps, type Context, DynamicComponent, type EffectOptions, ErrorBoundary, type ErrorBoundaryProps, ErrorDisplay, type ErrorDisplayProps, type ErrorSeverity, type FormProps, Fragment, type ImgProps, type InputProps, type InputType, KeepAlive, type KeepAliveOptions, type LabelProps, Loading, type LoadingProps, type LongPressOptions, type MediaProps, NodeChild, NodeChildren, type OptionProps, Portal, type Ref, type SelectProps, type SignalOptions, type SlotFn, type Slots, type StoreActions, Suspense, type SuspenseProps, TagProps, type TextareaProps, type TypedTagFunction, type VideoProps, __resetIdCounter, a, abbr, action, address, area, array, article, aside, asyncDerived, audio, autoResize, b, base, batch, bdi, bdo, bindDynamic, blockquote, body, br, button, canvas, caption, catchError, catchErrorAsync, center, checkLeaks, circle, cite, clickOutside, clipPath, code, col, colgroup, context, copyOnClick, createId, customElement, data, datalist, dd, deepEqual, deepSignal, defer, defs, del, derived, details, dfn, dialog, disableSSR, dispose, div, dl, dt, each, effect, ellipse, em, embed, enableSSR, enqueueBatchedSignal, fieldset, figcaption, figure, font, footer, form, g, getSlot, h1, h2, h3, h4, h5, h6, head, header, hr, html, i, iframe, img, input, ins, isBatching, isSSR, kbd, label, lazy, legend, li, line, linearGradient, link, longPress, main, map, mark, marker, marquee, mask, match, math, menu, meta, meter, mount, nav, nextTick, noscript, object, ol, on, onCleanup, onMount, onUnmount, optgroup, option, output, p, param, path, pattern, picture, polygon, polyline, portal, pre, progress, q, radialGradient, reactiveArray, rect, ref, registerComponent, registerDisposer, resolveComponent, rp, rt, ruby, s, samp, script, section, select, setGlobalErrorHandler, show, signal, slot, small, source, span, stop, store, strict, strictEffect, strong, style, sub, summary, sup, svg, symbol, table, tbody, td, template, text, textarea, tfoot, th, thead, time, title, tr, track, transition, trapFocus, tspan, u, ul, unregisterComponent, untracked, use, var_, video, watch, when, withSSR, writable };