sibujs 4.4.0 → 4.5.0

package/dist/tagFactory-DVoDpHye.d.cts

@@ -0,0 +1,215 @@
+declare const __accessor: unique symbol;
+/**
+ * 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(count)                       // ✓ reactive — Accessor passed directly
+ * div(() => count())               // ✓ reactive — explicit arrow wrapper
+ * div(count())                     // ✗ static  — evaluated once, not reactive
+ * ```
+ */
+type Accessor<T> = (() => T) & {
+    readonly [__accessor]?: never;
+};
+type SetState<T> = (next: T | ((prev: T) => T)) => void;
+type StateTuple<T> = [Accessor<T>, SetState<T>];
+/** Options for signal */
+interface SignalOptions<T = unknown> {
+    /** Debug name for devtools inspection. Only used in development. */
+    name?: string;
+    /** Custom equality function. Defaults to Object.is(). */
+    equals?: (prev: T, next: T) => boolean;
+}
+/**
+ * signal creates a reactive signal that holds a value of type T.
+ * Returns a tuple: [getter, setter].
+ *
+ * @param initial Initial value
+ * @param options Optional config: `{ name: "count" }` for devtools labeling
+ * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
+ * context subscribes to the signal; the setter accepts a value or an updater.
+ */
+declare function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>;
+/**
+ * A valueless reactive token standing in for state SibuJS does not own.
+ *
+ * See {@link external}.
+ */
+interface ExternalSource {
+    /**
+     * Declare, from inside a reactive computation, that it reads the external
+     * state this source represents. Call it in the same places you would read a
+     * signal — the top of a binding getter, a `derived()` body, an `effect()`.
+     *
+     * Outside a tracking context it is a no-op, exactly like reading a signal.
+     */
+    track(): void;
+    /**
+     * Declare that the external state changed. Every consumer that called
+     * {@link ExternalSource.track} is invalidated.
+     *
+     * Participates in `batch()` like any signal write: inside a batch, consumers
+     * are notified once when the outermost batch flushes.
+     */
+    invalidate(): void;
+}
+/**
+ * Create a reactive source for state that lives outside SibuJS — a domain
+ * engine, a media element, a canvas scene, an editor document, a cache a
+ * socket writes into.
+ *
+ * The pattern is two lines: `track()` where you read, `invalidate()` after you
+ * mutate.
+ *
+ * ```ts
+ * import { Chess } from "chess.js";
+ * import { external } from "sibujs";
+ *
+ * const game = new Chess();      // owns the rules and the mutable state
+ * const moved = external();      // owns "something changed"
+ *
+ * ctx.text("@status", () => {
+ *   moved.track();               // this binding reads the engine
+ *   return game.isCheckmate() ? "Checkmate" : `${game.turn()} to move`;
+ * });
+ *
+ * game.move({ from: "e2", to: "e4" });
+ * moved.invalidate();            // every consumer above re-reads
+ * ```
+ *
+ * **One source is one invalidation domain.** Every consumer of a source
+ * re-runs on every `invalidate()`, so the granularity of your updates is
+ * exactly the granularity of your sources: one for a whole engine is the
+ * cheapest to write, several (`board`, `clock`, `history`) let an update touch
+ * only what it affects. See `docs/architecture/external-state.md` for the
+ * trade-offs and when subdividing is worth it.
+ *
+ * Ownership, disposal and error routing are the consumer's, not the source's:
+ * a disposed binding or effect is never invalidated, and a consumer that
+ * throws is reported through the normal runtime error pipeline with its own
+ * phase and node.
+ *
+ * @param options `name` labels the source in devtools (development only).
+ */
+declare function external(options?: {
+    name?: string;
+}): ExternalSource;
+
+/**
+ * derived creates a derived reactive signal whose value updates when dependencies change.
+ *
+ * Uses lazy pull-based evaluation with a single dirty flag:
+ * - When a dependency changes, the computed is marked dirty (no re-evaluation).
+ * - Dirtiness propagates downstream via propagateDirty.
+ * - The getter only re-evaluates when actually read (pull-based).
+ * - On re-evaluation, dependencies are re-tracked via retrack() so that
+ *   derived-of-derived chains propagate correctly without paying the full
+ *   Set-delete + re-add cost of track()'s cleanup phase.
+ *
+ * STABILIZATION — why a dirty flag is enough:
+ *
+ * A dirty computed does NOT imply a changed value. Downstream effects are
+ * enqueued by `propagateDirty` at write time, before this computed has had a
+ * chance to recompute and compare. Rather than adding a three-color
+ * (CLEAN/CHECK/DIRTY) propagation pass — which an earlier revision measured as
+ * a regression on every benchmark, because the extra state has nothing to skip
+ * when values genuinely change — the engine settles the question lazily at
+ * DRAIN time: `cs._validate` recomputes a dirty computed and `cs.__v` is bumped
+ * ONLY when the new value differs under this computed's comparator. The
+ * scheduler compares that version against what each subscriber last observed
+ * and suppresses the run when nothing changed (see `depsChanged` in
+ * ../../reactivity/track-core.ts).
+ *
+ * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
+ * propagation, with recomputation still fully lazy: `_validate` only ever runs
+ * when an effect is genuinely about to observe the value.
+ *
+ * DISPOSAL — a derived subscribes to its sources when it is created, and those
+ * edges live as long as the sources do. A derived created per mount (one per
+ * virtualized row, say) must be released when its owner goes away:
+ * `flag.dispose()`, or `onCleanup(flag.dispose, rowNode)` to tie it to a node.
+ * A disposed accessor is inert: it keeps returning the last value it settled,
+ * never recomputes, never re-subscribes, and never wakes downstream readers.
+ * Disposal is idempotent.
+ *
+ * ERRORS — a recomputation that throws is thrown to the next reader, in that
+ * reader's context: a binding reports it with its node (so the nearest
+ * `ErrorBoundary` can claim it), an effect reports it, a direct caller can catch
+ * it, and a derived reading another derived passes it on. A live derived stays
+ * dirty and recomputes on the following read; a derived that disposed itself
+ * during the failing run returns its frozen value afterwards.
+ *
+ * @returns An accessor for the computed value. It recomputes lazily on read
+ * after any dependency changes, and carries `dispose()` to release its source
+ * subscriptions.
+ */
+declare function derived<T>(getter: () => T, options?: {
+    name?: string;
+    /** Custom equality — when the recomputed value equals the previous,
+     *  downstream subscribers are not notified. Defaults to `Object.is`. */
+    equals?: (a: T, b: T) => boolean;
+}): DerivedAccessor<T>;
+/** Accessor returned by {@link derived}: read it like any getter, release it with `dispose()`. */
+type DerivedAccessor<T> = Accessor<T> & {
+    /** Release every source subscription. The accessor then returns its last settled value. Idempotent. */
+    dispose: () => void;
+};
+
+/**
+ * Canonical disposer/teardown signature used across the framework.
+ *
+ * Returned by `effect()`, `track()`, widget `bind()` methods, and other
+ * subscription/lifecycle helpers. All disposers MUST be idempotent — calling
+ * twice should be a no-op rather than an error.
+ */
+type Dispose = () => void;
+type NodeChild = Node | Element | Text | Comment | string | number | boolean | (() => NodeChild) | null | undefined;
+type NodeChildren = NodeChild | NodeChild[] | NodeChild[][] | (() => NodeChild | NodeChild[]);
+
+declare const SVG_NS = "http://www.w3.org/2000/svg";
+interface TagProps {
+    id?: string;
+    class?: string | (() => string) | Record<string, boolean | (() => boolean)>;
+    style?: Record<string, string | number | (() => string | number)> | string | (() => string);
+    ref?: {
+        current: Element | null;
+    };
+    nodes?: NodeChildren;
+    on?: Record<string, (ev: Event) => void>;
+    /** Called with the element after creation — useful for imperative bindings */
+    onElement?: (el: HTMLElement) => void;
+    [attr: string]: unknown;
+}
+/**
+ * Factory for creating HTML or SVG elements with reactive props and nodes.
+ *
+ * Calling conventions:
+ *
+ *   tag()                         empty element
+ *   tag("text")                   element with text content
+ *   tag(42)                       element with numeric text content
+ *   tag([childA, childB])         element with children (array)
+ *   tag(node)                     element wrapping a single existing node
+ *   tag(getter)                   element with a reactive child
+ *   tag("className", children)    positional: class + children
+ *   tag({ ...props })             full props object (children via props.nodes)
+ *   tag({ ...props }, children)   props + children (no need for `nodes:` key!)
+ *
+ * The last form is the "deeply-nested shorthand" the codebase favours:
+ *
+ *   div({ class: "card" }, [
+ *     h1({ class: "title" }, "Hello"),
+ *     p({ class: "body" }, "World"),
+ *     div({ class: "row" }, [
+ *       span({ id: "x" }, "child"),
+ *     ]),
+ *   ])
+ *
+ * `children` overrides `props.nodes` when both are present.
+ */
+declare const tagFactory: (tag: string, ns?: string) => (first?: TagProps | NodeChildren, second?: NodeChildren) => Element;
+
+export { type Accessor as A, type DerivedAccessor as D, type ExternalSource as E, type NodeChild as N, SVG_NS as S, type TagProps as T, type NodeChildren as a, type Dispose as b, type SignalOptions as c, derived as d, external as e, signal as s, tagFactory as t };

package/dist/tagFactory-DVoDpHye.d.ts

@@ -0,0 +1,215 @@
+declare const __accessor: unique symbol;
+/**
+ * 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(count)                       // ✓ reactive — Accessor passed directly
+ * div(() => count())               // ✓ reactive — explicit arrow wrapper
+ * div(count())                     // ✗ static  — evaluated once, not reactive
+ * ```
+ */
+type Accessor<T> = (() => T) & {
+    readonly [__accessor]?: never;
+};
+type SetState<T> = (next: T | ((prev: T) => T)) => void;
+type StateTuple<T> = [Accessor<T>, SetState<T>];
+/** Options for signal */
+interface SignalOptions<T = unknown> {
+    /** Debug name for devtools inspection. Only used in development. */
+    name?: string;
+    /** Custom equality function. Defaults to Object.is(). */
+    equals?: (prev: T, next: T) => boolean;
+}
+/**
+ * signal creates a reactive signal that holds a value of type T.
+ * Returns a tuple: [getter, setter].
+ *
+ * @param initial Initial value
+ * @param options Optional config: `{ name: "count" }` for devtools labeling
+ * @returns A `[getter, setter]` tuple. Calling the getter inside a reactive
+ * context subscribes to the signal; the setter accepts a value or an updater.
+ */
+declare function signal<T>(initial: T, options?: SignalOptions<T>): StateTuple<T>;
+/**
+ * A valueless reactive token standing in for state SibuJS does not own.
+ *
+ * See {@link external}.
+ */
+interface ExternalSource {
+    /**
+     * Declare, from inside a reactive computation, that it reads the external
+     * state this source represents. Call it in the same places you would read a
+     * signal — the top of a binding getter, a `derived()` body, an `effect()`.
+     *
+     * Outside a tracking context it is a no-op, exactly like reading a signal.
+     */
+    track(): void;
+    /**
+     * Declare that the external state changed. Every consumer that called
+     * {@link ExternalSource.track} is invalidated.
+     *
+     * Participates in `batch()` like any signal write: inside a batch, consumers
+     * are notified once when the outermost batch flushes.
+     */
+    invalidate(): void;
+}
+/**
+ * Create a reactive source for state that lives outside SibuJS — a domain
+ * engine, a media element, a canvas scene, an editor document, a cache a
+ * socket writes into.
+ *
+ * The pattern is two lines: `track()` where you read, `invalidate()` after you
+ * mutate.
+ *
+ * ```ts
+ * import { Chess } from "chess.js";
+ * import { external } from "sibujs";
+ *
+ * const game = new Chess();      // owns the rules and the mutable state
+ * const moved = external();      // owns "something changed"
+ *
+ * ctx.text("@status", () => {
+ *   moved.track();               // this binding reads the engine
+ *   return game.isCheckmate() ? "Checkmate" : `${game.turn()} to move`;
+ * });
+ *
+ * game.move({ from: "e2", to: "e4" });
+ * moved.invalidate();            // every consumer above re-reads
+ * ```
+ *
+ * **One source is one invalidation domain.** Every consumer of a source
+ * re-runs on every `invalidate()`, so the granularity of your updates is
+ * exactly the granularity of your sources: one for a whole engine is the
+ * cheapest to write, several (`board`, `clock`, `history`) let an update touch
+ * only what it affects. See `docs/architecture/external-state.md` for the
+ * trade-offs and when subdividing is worth it.
+ *
+ * Ownership, disposal and error routing are the consumer's, not the source's:
+ * a disposed binding or effect is never invalidated, and a consumer that
+ * throws is reported through the normal runtime error pipeline with its own
+ * phase and node.
+ *
+ * @param options `name` labels the source in devtools (development only).
+ */
+declare function external(options?: {
+    name?: string;
+}): ExternalSource;
+
+/**
+ * derived creates a derived reactive signal whose value updates when dependencies change.
+ *
+ * Uses lazy pull-based evaluation with a single dirty flag:
+ * - When a dependency changes, the computed is marked dirty (no re-evaluation).
+ * - Dirtiness propagates downstream via propagateDirty.
+ * - The getter only re-evaluates when actually read (pull-based).
+ * - On re-evaluation, dependencies are re-tracked via retrack() so that
+ *   derived-of-derived chains propagate correctly without paying the full
+ *   Set-delete + re-add cost of track()'s cleanup phase.
+ *
+ * STABILIZATION — why a dirty flag is enough:
+ *
+ * A dirty computed does NOT imply a changed value. Downstream effects are
+ * enqueued by `propagateDirty` at write time, before this computed has had a
+ * chance to recompute and compare. Rather than adding a three-color
+ * (CLEAN/CHECK/DIRTY) propagation pass — which an earlier revision measured as
+ * a regression on every benchmark, because the extra state has nothing to skip
+ * when values genuinely change — the engine settles the question lazily at
+ * DRAIN time: `cs._validate` recomputes a dirty computed and `cs.__v` is bumped
+ * ONLY when the new value differs under this computed's comparator. The
+ * scheduler compares that version against what each subscriber last observed
+ * and suppresses the run when nothing changed (see `depsChanged` in
+ * ../../reactivity/track-core.ts).
+ *
+ * That keeps the cheap boolean dirty flag AND makes `equals` actually stop
+ * propagation, with recomputation still fully lazy: `_validate` only ever runs
+ * when an effect is genuinely about to observe the value.
+ *
+ * DISPOSAL — a derived subscribes to its sources when it is created, and those
+ * edges live as long as the sources do. A derived created per mount (one per
+ * virtualized row, say) must be released when its owner goes away:
+ * `flag.dispose()`, or `onCleanup(flag.dispose, rowNode)` to tie it to a node.
+ * A disposed accessor is inert: it keeps returning the last value it settled,
+ * never recomputes, never re-subscribes, and never wakes downstream readers.
+ * Disposal is idempotent.
+ *
+ * ERRORS — a recomputation that throws is thrown to the next reader, in that
+ * reader's context: a binding reports it with its node (so the nearest
+ * `ErrorBoundary` can claim it), an effect reports it, a direct caller can catch
+ * it, and a derived reading another derived passes it on. A live derived stays
+ * dirty and recomputes on the following read; a derived that disposed itself
+ * during the failing run returns its frozen value afterwards.
+ *
+ * @returns An accessor for the computed value. It recomputes lazily on read
+ * after any dependency changes, and carries `dispose()` to release its source
+ * subscriptions.
+ */
+declare function derived<T>(getter: () => T, options?: {
+    name?: string;
+    /** Custom equality — when the recomputed value equals the previous,
+     *  downstream subscribers are not notified. Defaults to `Object.is`. */
+    equals?: (a: T, b: T) => boolean;
+}): DerivedAccessor<T>;
+/** Accessor returned by {@link derived}: read it like any getter, release it with `dispose()`. */
+type DerivedAccessor<T> = Accessor<T> & {
+    /** Release every source subscription. The accessor then returns its last settled value. Idempotent. */
+    dispose: () => void;
+};
+
+/**
+ * Canonical disposer/teardown signature used across the framework.
+ *
+ * Returned by `effect()`, `track()`, widget `bind()` methods, and other
+ * subscription/lifecycle helpers. All disposers MUST be idempotent — calling
+ * twice should be a no-op rather than an error.
+ */
+type Dispose = () => void;
+type NodeChild = Node | Element | Text | Comment | string | number | boolean | (() => NodeChild) | null | undefined;
+type NodeChildren = NodeChild | NodeChild[] | NodeChild[][] | (() => NodeChild | NodeChild[]);
+
+declare const SVG_NS = "http://www.w3.org/2000/svg";
+interface TagProps {
+    id?: string;
+    class?: string | (() => string) | Record<string, boolean | (() => boolean)>;
+    style?: Record<string, string | number | (() => string | number)> | string | (() => string);
+    ref?: {
+        current: Element | null;
+    };
+    nodes?: NodeChildren;
+    on?: Record<string, (ev: Event) => void>;
+    /** Called with the element after creation — useful for imperative bindings */
+    onElement?: (el: HTMLElement) => void;
+    [attr: string]: unknown;
+}
+/**
+ * Factory for creating HTML or SVG elements with reactive props and nodes.
+ *
+ * Calling conventions:
+ *
+ *   tag()                         empty element
+ *   tag("text")                   element with text content
+ *   tag(42)                       element with numeric text content
+ *   tag([childA, childB])         element with children (array)
+ *   tag(node)                     element wrapping a single existing node
+ *   tag(getter)                   element with a reactive child
+ *   tag("className", children)    positional: class + children
+ *   tag({ ...props })             full props object (children via props.nodes)
+ *   tag({ ...props }, children)   props + children (no need for `nodes:` key!)
+ *
+ * The last form is the "deeply-nested shorthand" the codebase favours:
+ *
+ *   div({ class: "card" }, [
+ *     h1({ class: "title" }, "Hello"),
+ *     p({ class: "body" }, "World"),
+ *     div({ class: "row" }, [
+ *       span({ id: "x" }, "child"),
+ *     ]),
+ *   ])
+ *
+ * `children` overrides `props.nodes` when both are present.
+ */
+declare const tagFactory: (tag: string, ns?: string) => (first?: TagProps | NodeChildren, second?: NodeChildren) => Element;
+
+export { type Accessor as A, type DerivedAccessor as D, type ExternalSource as E, type NodeChild as N, SVG_NS as S, type TagProps as T, type NodeChildren as a, type Dispose as b, type SignalOptions as c, derived as d, external as e, signal as s, tagFactory as t };

package/dist/testing.cjs

@@ -1821,6 +1821,15 @@ function untracked(fn) {
 var subscriberEpochCounter = 0;
 function retrack(effectFn, subscriber) {
   const prev = currentSubscriber;
+  let savedDepth = 0;
+  let savedSuspendSub = null;
+  if (trackingSuspended) {
+    savedDepth = suspendDepth;
+    savedSuspendSub = suspendSavedSub;
+    suspendDepth = 0;
+    suspendSavedSub = null;
+    trackingSuspended = false;
+  }
   currentSubscriber = subscriber;
   const sub = subscriber;
   const epoch = ++subscriberEpochCounter;
@@ -1835,6 +1844,11 @@ function retrack(effectFn, subscriber) {
     effectFn();
   } finally {
     currentSubscriber = prev;
+    if (savedDepth !== 0) {
+      suspendDepth = savedDepth;
+      suspendSavedSub = savedSuspendSub;
+      trackingSuspended = true;
+    }
     let node = sub.depsHead ?? null;
     while (node !== null) {
       const next = node.subNext;
@@ -1854,11 +1868,25 @@ function track(effectFn, subscriber) {
   if (!subscriber) return reactiveBinding(effectFn);
   cleanup(subscriber);
   const prev = currentSubscriber;
+  let savedDepth = 0;
+  let savedSuspendSub = null;
+  if (trackingSuspended) {
+    savedDepth = suspendDepth;
+    savedSuspendSub = suspendSavedSub;
+    suspendDepth = 0;
+    suspendSavedSub = null;
+    trackingSuspended = false;
+  }
   currentSubscriber = subscriber;
   try {
     effectFn();
   } finally {
     currentSubscriber = prev;
+    if (savedDepth !== 0) {
+      suspendDepth = savedDepth;
+      suspendSavedSub = savedSuspendSub;
+      trackingSuspended = true;
+    }
     const sub2 = subscriber;
     for (let n = sub2.depsHead ?? null; n !== null; n = n.subNext) {
       const sig = n.sig;
@@ -2029,8 +2057,9 @@ function propagateDirty(sub) {
         if (s._c) {
           const nSig = s._sig;
           if (nSig) {
-            if (!nSig._d) {
+            if (!nSig._d || nSig._f === true) {
               nSig._d = true;
+              nSig._f = false;
               stack.push(nSig);
             }
           } else {
@@ -2130,7 +2159,7 @@ function forEachSubscriber(signal, visit) {
 }
 
 // src/reactivity/track.ts
-var _runtimeVersion = true ? "4.4.0" : "dev";
+var _runtimeVersion = true ? "4.5.0" : "dev";
 var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("sibujs.reactive.v1");
 function resolveReactiveApi() {
   const g = globalThis;

package/dist/testing.js

@@ -3,12 +3,12 @@ import {
 } from "./chunk-7ZHH77QA.js";
 import {
   effect
-} from "./chunk-7GIHSAWB.js";
+} from "./chunk-RIXRAYIU.js";
 import "./chunk-5DXA2J44.js";
 import {
   replaceChildrenSafely
 } from "./chunk-QKRPLZ2V.js";
-import "./chunk-3BTTCZ5J.js";
+import "./chunk-UGRX3S57.js";
 import "./chunk-2WLZ6757.js";
 
 // src/testing/a11y.ts