sibujs 4.5.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-DVoDpHye.d.ts → tagFactory-DFstCLQV.d.cts}

@@ -1,102 +1,4 @@
-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;
+import { A as Accessor } from './signal-EotCj4hS.cjs';
 
 /**
  * derived creates a derived reactive signal whose value updates when dependencies change.
@@ -212,4 +114,4 @@ interface TagProps {
  */
 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 };
+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-DVoDpHye.d.cts → tagFactory-DkaNVUNV.d.ts}

@@ -1,102 +1,4 @@
-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;
+import { A as Accessor } from './signal-EotCj4hS.js';
 
 /**
  * derived creates a derived reactive signal whose value updates when dependencies change.
@@ -212,4 +114,4 @@ interface TagProps {
  */
 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 };
+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 };