sibujs 4.4.0 → 4.6.0

package/dist/{startup-BMpaiMhP.d.ts → startup-BLfSeL15.d.cts}

@@ -26,32 +26,45 @@ declare function createModuleRegistry(): {
  * Returns an object with only the requested exports.
  */
 declare function createBundle<T extends object>(modules: Record<string, () => unknown>): T;
+/** Handle returned by {@link lazyModule}. */
+interface LazyModule<T> {
+    /** Whether a load has completed successfully. Read-only. */
+    readonly loaded: boolean;
+    /** Load the module (once) and resolve to it. Concurrent calls share one load. */
+    get(): Promise<T>;
+}
 /**
  * Lazy module loader that only imports a module when first accessed.
  * Uses ES module dynamic import under the hood.
  * Caches the result after the first successful load.
+ *
+ * Concurrent `get()` calls made before the first load settles share that one
+ * load. A failed load is not cached: the next `get()` retries.
  */
-declare function lazyModule<T>(loader: () => Promise<T>): {
-    get: () => Promise<T>;
-    loaded: boolean;
+declare function lazyModule<T>(loader: () => Promise<T>): LazyModule<T>;
+/** One `exports` entry: a module entry point, or a prebuilt CDN script. */
+type PackageExportTarget = {
+    types: string;
+    import: string;
+    require: string;
+} | {
+    default: string;
 };
 /**
  * Package metadata for distribution tooling.
- * Provides entry point information and can generate Node.js subpath exports maps.
+ * Provides entry point information and generates the Node.js subpath exports
+ * map that the published package actually uses.
  */
 declare const packageInfo: {
     name: string;
     version: string;
     entryPoints: Record<string, string>;
     /**
-     * Generate a package.json `exports` map for Node.js subpath exports.
-     * Maps each entry point to its import, require, and types paths.
+     * Generate the package.json `exports` map. Module entries resolve to the
+     * `.js` (ESM), `.cjs` and `.d.ts` files tsup emits into `dist/`; CDN entries
+     * resolve to their prebuilt global script.
      */
-    generateExportsMap(): Record<string, {
-        import: string;
-        require: string;
-        types: string;
-    }>;
+    generateExportsMap(): Record<string, PackageExportTarget>;
 };
 
 /**
@@ -127,16 +140,14 @@ declare const env: {
     isTest: boolean;
 };
 
-/**
- * Versioning and migration utilities for SibuJS applications.
- * Provides semantic version management, migration tooling, and compatibility checks.
- */
 /** Semantic version representation */
 interface SemVer {
     major: number;
     minor: number;
     patch: number;
     prerelease?: string;
+    /** Build metadata (after `+`). Ignored when comparing versions. */
+    build?: string;
 }
 /** Migration definition */
 interface Migration {
@@ -146,11 +157,19 @@ interface Migration {
     down?: () => void | Promise<void>;
 }
 /**
- * Framework version constant.
+ * Framework version: the published package version, stamped at build time.
+ * Only raw, unbundled source reports "dev". (It was hard-coded to "1.0.0", so
+ * compatibility checks compared against a version the package never had.)
  */
-declare const VERSION = "1.0.0";
+declare const VERSION: string;
 /**
  * Parse a semantic version string into components.
+ *
+ * Accepts full SemVer 2.0.0 (`1.2.3`, `1.2.3-beta.1`, `1.2.3+build.5`), an
+ * optional leading `v`, surrounding whitespace, and the abbreviated `1` and
+ * `1.2` forms. Anything else — trailing characters, extra components, empty or
+ * illegal identifiers, numeric leading zeros — throws. (`parseInt` used to accept
+ * numeric prefixes such as `1.2.3garbage` and ignore extra components.)
  */
 declare function parseSemVer(version: string): SemVer;
 /**
@@ -162,22 +181,46 @@ declare function compareSemVer(a: string | SemVer, b: string | SemVer): -1 | 0 |
  * Check if a version satisfies a semver range (supports ^, ~, >=, <=, =).
  */
 declare function satisfies(version: string, range: string): boolean;
+/**
+ * A migration step succeeded but recording its version in storage failed.
+ *
+ * Reported separately from a failing `up()` / `down()` because the migration's
+ * own work DID happen: storage is now behind reality and needs attention, but
+ * the step itself must not be retried as if it had failed.
+ */
+declare class MigrationStorageError extends Error {
+    /** The migration whose checkpoint could not be written. */
+    readonly version: string;
+    constructor(version: string, cause: unknown);
+}
 /**
  * Create a migration runner for managing schema/state version upgrades.
+ *
+ * `migrate()` and `rollback()` are serialized across ALL runners in this realm
+ * that use the same storage object and storage key; runners with a different
+ * key (or storage) run independently. Coordination does not extend across
+ * tabs or workers.
  */
 declare function createMigrationRunner(config: {
     /** Current version of the app/data */
     currentVersion: string;
     /** Storage key for persisting applied migration version */
     storageKey?: string;
+    /** Storage holding the applied version (default: `localStorage`) */
+    storage?: Storage;
     /** Available migrations, sorted by version */
     migrations: Migration[];
 }): {
     /** Get the last applied migration version from storage */
-    getAppliedVersion(): string | null;
+    getAppliedVersion: () => string | null;
     /** Get pending migrations that haven't been applied */
-    getPending(): Migration[];
-    /** Run all pending migrations in order */
+    getPending: () => Migration[];
+    /**
+     * Run all pending migrations in order. Concurrent calls (and calls racing
+     * `rollback()`) run one after another, each recomputing what is pending —
+     * on this runner and on every other runner in this realm sharing its
+     * storage and storage key.
+     */
     migrate(): Promise<{
         applied: string[];
         errors: Array<{
@@ -185,7 +228,15 @@ declare function createMigrationRunner(config: {
             error: Error;
         }>;
     }>;
-    /** Rollback to a specific version */
+    /**
+     * Rollback to a specific version.
+     *
+     * The applied version is checkpointed after EVERY successful `down()`, so a
+     * rollback that fails part-way leaves storage describing what is actually
+     * still applied, and a retry does not repeat completed `down()` steps.
+     * Throws the failing `down()`'s error, a missing-`down()` error, or a
+     * {@link MigrationStorageError} if a checkpoint cannot be written.
+     */
     rollback(targetVersion: string): Promise<{
         rolledBack: string[];
     }>;
@@ -288,4 +339,4 @@ declare function createBootSequence(): {
     }>;
 };
 
-export { type Migration as M, type SemVer as S, VERSION as V, compareSemVer as a, bundlerMetadata as b, checkCompatibility as c, createBootSequence as d, createBundle as e, createMigrationRunner as f, createModuleRegistry as g, createSSRCache as h, createTestHarness as i, deferNonCritical as j, env as k, healthCheck as l, lazyModule as m, parseSemVer as n, preloadCritical as o, packageInfo as p, prerenderRoutes as q, satisfies as s };
+export { type LazyModule as L, type Migration as M, type PackageExportTarget as P, type SemVer as S, VERSION as V, MigrationStorageError as a, bundlerMetadata as b, checkCompatibility as c, compareSemVer as d, createBootSequence as e, createBundle as f, createMigrationRunner as g, createModuleRegistry as h, createSSRCache as i, createTestHarness as j, deferNonCritical as k, env as l, healthCheck as m, lazyModule as n, parseSemVer as o, packageInfo as p, preloadCritical as q, prerenderRoutes as r, satisfies as s };

package/dist/{startup-BMpaiMhP.d.cts → startup-BLfSeL15.d.ts}

@@ -26,32 +26,45 @@ declare function createModuleRegistry(): {
  * Returns an object with only the requested exports.
  */
 declare function createBundle<T extends object>(modules: Record<string, () => unknown>): T;
+/** Handle returned by {@link lazyModule}. */
+interface LazyModule<T> {
+    /** Whether a load has completed successfully. Read-only. */
+    readonly loaded: boolean;
+    /** Load the module (once) and resolve to it. Concurrent calls share one load. */
+    get(): Promise<T>;
+}
 /**
  * Lazy module loader that only imports a module when first accessed.
  * Uses ES module dynamic import under the hood.
  * Caches the result after the first successful load.
+ *
+ * Concurrent `get()` calls made before the first load settles share that one
+ * load. A failed load is not cached: the next `get()` retries.
  */
-declare function lazyModule<T>(loader: () => Promise<T>): {
-    get: () => Promise<T>;
-    loaded: boolean;
+declare function lazyModule<T>(loader: () => Promise<T>): LazyModule<T>;
+/** One `exports` entry: a module entry point, or a prebuilt CDN script. */
+type PackageExportTarget = {
+    types: string;
+    import: string;
+    require: string;
+} | {
+    default: string;
 };
 /**
  * Package metadata for distribution tooling.
- * Provides entry point information and can generate Node.js subpath exports maps.
+ * Provides entry point information and generates the Node.js subpath exports
+ * map that the published package actually uses.
  */
 declare const packageInfo: {
     name: string;
     version: string;
     entryPoints: Record<string, string>;
     /**
-     * Generate a package.json `exports` map for Node.js subpath exports.
-     * Maps each entry point to its import, require, and types paths.
+     * Generate the package.json `exports` map. Module entries resolve to the
+     * `.js` (ESM), `.cjs` and `.d.ts` files tsup emits into `dist/`; CDN entries
+     * resolve to their prebuilt global script.
      */
-    generateExportsMap(): Record<string, {
-        import: string;
-        require: string;
-        types: string;
-    }>;
+    generateExportsMap(): Record<string, PackageExportTarget>;
 };
 
 /**
@@ -127,16 +140,14 @@ declare const env: {
     isTest: boolean;
 };
 
-/**
- * Versioning and migration utilities for SibuJS applications.
- * Provides semantic version management, migration tooling, and compatibility checks.
- */
 /** Semantic version representation */
 interface SemVer {
     major: number;
     minor: number;
     patch: number;
     prerelease?: string;
+    /** Build metadata (after `+`). Ignored when comparing versions. */
+    build?: string;
 }
 /** Migration definition */
 interface Migration {
@@ -146,11 +157,19 @@ interface Migration {
     down?: () => void | Promise<void>;
 }
 /**
- * Framework version constant.
+ * Framework version: the published package version, stamped at build time.
+ * Only raw, unbundled source reports "dev". (It was hard-coded to "1.0.0", so
+ * compatibility checks compared against a version the package never had.)
  */
-declare const VERSION = "1.0.0";
+declare const VERSION: string;
 /**
  * Parse a semantic version string into components.
+ *
+ * Accepts full SemVer 2.0.0 (`1.2.3`, `1.2.3-beta.1`, `1.2.3+build.5`), an
+ * optional leading `v`, surrounding whitespace, and the abbreviated `1` and
+ * `1.2` forms. Anything else — trailing characters, extra components, empty or
+ * illegal identifiers, numeric leading zeros — throws. (`parseInt` used to accept
+ * numeric prefixes such as `1.2.3garbage` and ignore extra components.)
  */
 declare function parseSemVer(version: string): SemVer;
 /**
@@ -162,22 +181,46 @@ declare function compareSemVer(a: string | SemVer, b: string | SemVer): -1 | 0 |
  * Check if a version satisfies a semver range (supports ^, ~, >=, <=, =).
  */
 declare function satisfies(version: string, range: string): boolean;
+/**
+ * A migration step succeeded but recording its version in storage failed.
+ *
+ * Reported separately from a failing `up()` / `down()` because the migration's
+ * own work DID happen: storage is now behind reality and needs attention, but
+ * the step itself must not be retried as if it had failed.
+ */
+declare class MigrationStorageError extends Error {
+    /** The migration whose checkpoint could not be written. */
+    readonly version: string;
+    constructor(version: string, cause: unknown);
+}
 /**
  * Create a migration runner for managing schema/state version upgrades.
+ *
+ * `migrate()` and `rollback()` are serialized across ALL runners in this realm
+ * that use the same storage object and storage key; runners with a different
+ * key (or storage) run independently. Coordination does not extend across
+ * tabs or workers.
  */
 declare function createMigrationRunner(config: {
     /** Current version of the app/data */
     currentVersion: string;
     /** Storage key for persisting applied migration version */
     storageKey?: string;
+    /** Storage holding the applied version (default: `localStorage`) */
+    storage?: Storage;
     /** Available migrations, sorted by version */
     migrations: Migration[];
 }): {
     /** Get the last applied migration version from storage */
-    getAppliedVersion(): string | null;
+    getAppliedVersion: () => string | null;
     /** Get pending migrations that haven't been applied */
-    getPending(): Migration[];
-    /** Run all pending migrations in order */
+    getPending: () => Migration[];
+    /**
+     * Run all pending migrations in order. Concurrent calls (and calls racing
+     * `rollback()`) run one after another, each recomputing what is pending —
+     * on this runner and on every other runner in this realm sharing its
+     * storage and storage key.
+     */
     migrate(): Promise<{
         applied: string[];
         errors: Array<{
@@ -185,7 +228,15 @@ declare function createMigrationRunner(config: {
             error: Error;
         }>;
     }>;
-    /** Rollback to a specific version */
+    /**
+     * Rollback to a specific version.
+     *
+     * The applied version is checkpointed after EVERY successful `down()`, so a
+     * rollback that fails part-way leaves storage describing what is actually
+     * still applied, and a retry does not repeat completed `down()` steps.
+     * Throws the failing `down()`'s error, a missing-`down()` error, or a
+     * {@link MigrationStorageError} if a checkpoint cannot be written.
+     */
     rollback(targetVersion: string): Promise<{
         rolledBack: string[];
     }>;
@@ -288,4 +339,4 @@ declare function createBootSequence(): {
     }>;
 };
 
-export { type Migration as M, type SemVer as S, VERSION as V, compareSemVer as a, bundlerMetadata as b, checkCompatibility as c, createBootSequence as d, createBundle as e, createMigrationRunner as f, createModuleRegistry as g, createSSRCache as h, createTestHarness as i, deferNonCritical as j, env as k, healthCheck as l, lazyModule as m, parseSemVer as n, preloadCritical as o, packageInfo as p, prerenderRoutes as q, satisfies as s };
+export { type LazyModule as L, type Migration as M, type PackageExportTarget as P, type SemVer as S, VERSION as V, MigrationStorageError as a, bundlerMetadata as b, checkCompatibility as c, compareSemVer as d, createBootSequence as e, createBundle as f, createMigrationRunner as g, createModuleRegistry as h, createSSRCache as i, createTestHarness as j, deferNonCritical as k, env as l, healthCheck as m, lazyModule as n, parseSemVer as o, packageInfo as p, preloadCritical as q, prerenderRoutes as r, satisfies as s };

package/dist/tagFactory-DFstCLQV.d.cts

@@ -0,0 +1,117 @@
+import { A as Accessor } from './signal-EotCj4hS.cjs';
+
+/**
+ * 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 DerivedAccessor as D, type NodeChild as N, SVG_NS as S, type TagProps as T, type NodeChildren as a, type Dispose as b, derived as d, tagFactory as t };

package/dist/tagFactory-DkaNVUNV.d.ts

@@ -0,0 +1,117 @@
+import { A as Accessor } from './signal-EotCj4hS.js';
+
+/**
+ * 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 DerivedAccessor as D, type NodeChild as N, SVG_NS as S, type TagProps as T, type NodeChildren as a, type Dispose as b, derived as d, tagFactory as t };