sibujs 4.12.0 → 4.13.1

package/dist/routeMiddleware-CedQTsLK.d.cts

@@ -0,0 +1,688 @@
+import { C as Component } from './types-CJFViL6Q.cjs';
+
+interface HeadProps {
+    title?: string | (() => string);
+    meta?: Record<string, string | (() => string)>[];
+    /**
+     * `<link>` elements to add to `<head>`.
+     *
+     * TRUST BOUNDARY for stylesheets: `{ rel: "stylesheet", href }` is the
+     * framework's explicit API for a stylesheet whose URL is a runtime value.
+     * The generic writers refuse to let a runtime `href` become an applied
+     * stylesheet at all (see `utils/elementPolicy.ts`), because a well-formed
+     * URL is not trusted CSS. Naming it here is the trust decision: first-party
+     * or pinned URLs only, and a CSP `style-src` as the second layer.
+     */
+    link?: Record<string, string>[];
+    /**
+     * External scripts to add to `<head>`.
+     *
+     * TRUST BOUNDARY: this is the framework's explicit API for loading a script
+     * whose URL is a runtime value, and naming it here IS the trust decision —
+     * the URL passes the scheme allowlist, but an allowed `https:` URL is still a
+     * program that runs with the page's full authority. Pass only URLs you
+     * control or pin (a first-party path, a CDN URL with `integrity`). The
+     * generic writers refuse to let a runtime value choose a `<script>` source
+     * at all; see `docs/architecture/attribute-security.md` § Trust model.
+     */
+    script?: Record<string, string>[];
+    /**
+     * The document `<base>`.
+     *
+     * TRUST BOUNDARY: `href` passes the scheme allowlist, but an allowed `https:`
+     * base still re-homes every relative URL on the page — relative `<script
+     * src>`, stylesheets, form actions and `fetch("/api")` alike. Treat it like a
+     * script URL: first-party values only.
+     */
+    base?: {
+        href?: string;
+        target?: string;
+    };
+}
+/**
+ * Head() manages document <head> tags reactively.
+ *
+ * META SECURITY: each meta entry is committed TRANSACTIONALLY. All of its
+ * attributes — static and reactive — are resolved into one snapshot, duplicate
+ * case-insensitive names are rejected, and the assembled snapshot is validated
+ * against the shared meta-refresh policy before anything reaches the DOM. An
+ * approved snapshot is then materialised on a fresh `<meta>` element while it is
+ * still detached and swapped in with a single `replaceWith()`, so no partially
+ * updated element is ever connected. A snapshot that fails validation withdraws
+ * the element entirely. See `utils/metaRefresh.ts`; the same policy governs SSR.
+ *
+ * NATIVE REFRESH DIRECTIVES MUST BE STATIC. A browser processes a meta refresh
+ * when the element is INSERTED — it records the pending navigation there and
+ * then, and removing or replacing the element afterwards is not a defined way to
+ * cancel it. `Head()` therefore never publishes a snapshot whose effective
+ * `http-equiv` is `refresh` from an entry that contains any reactive attribute,
+ * even when the destination is allowed: what cannot be withdrawn must not be
+ * handed over. Static refresh directives work as before, and every other
+ * reactive meta entry — description, keywords, Open Graph, non-refresh
+ * `http-equiv` — is unaffected.
+ *
+ * Supports dynamic title, meta tags, link tags, and structured data.
+ * Each instance tracks its own elements and effects for independent cleanup.
+ */
+declare function Head(props: HeadProps): Comment;
+/**
+ * Sets structured data (JSON-LD) for SEO.
+ *
+ * Security: the serialized JSON is passed through `escapeScriptJsonLocal`
+ * which unicode-escapes `<`, `>`, `&`, `U+2028`, and `U+2029`. This is
+ * defense-in-depth: when the element is inserted via `document.createElement`
+ * + `textContent` the browser will NOT re-parse the body, so `</script>`
+ * cannot break out of the tag at insertion time. However, tools that
+ * later serialize `document.head.innerHTML` DO re-parse, and the server
+ * side of any SSR roundtrip would see the raw text. Escaping here makes
+ * both paths safe.
+ */
+declare function setStructuredData(data: Record<string, unknown>): void;
+/**
+ * Sets the canonical URL for the page.
+ */
+declare function setCanonical(url: string): void;
+
+interface UseWorkerReturn<TInput, TOutput> {
+    post(data: TInput): void;
+    result: () => TOutput | null;
+    error: () => Error | null;
+    loading: () => boolean;
+    terminate(): void;
+}
+/**
+ * worker creates a Web Worker from an inline function and provides
+ * reactive state for its result, error, and loading status.
+ *
+ * The workerFn receives messages via the standard `onmessage` handler
+ * and should call `postMessage` to send results back. It is serialized
+ * into a Blob URL, so it must be self-contained (no closures).
+ *
+ * **CSP Warning:** This function serializes the provided function via `.toString()`
+ * and executes it inside a `blob:` URL Worker. This is equivalent to `eval()` and
+ * is incompatible with strict Content Security Policies that restrict
+ * `worker-src 'self'` or block `blob:` URLs. Additionally:
+ * - Minifiers may break captured variable references (closures silently fail).
+ * - Module-level imports are NOT accessible inside the worker.
+ * - Never pass user-controlled or dynamically constructed functions — this
+ *   would be equivalent to `eval()` on untrusted input.
+ *
+ * @param workerFn The function body to run inside the worker.
+ *                 It receives `self` as the worker global scope.
+ * @returns An object with post, result, error, loading, and terminate.
+ */
+declare function worker<TInput = unknown, TOutput = unknown>(workerFn: (e: MessageEvent<TInput>) => void): UseWorkerReturn<TInput, TOutput>;
+interface UseWorkerFnReturn<TArgs extends unknown[], TResult> {
+    run(...args: TArgs): Promise<TResult>;
+    loading: () => boolean;
+    terminate(): void;
+}
+/**
+ * workerFn wraps a pure function so it runs inside a Web Worker.
+ *
+ * The function must be self-contained -- it cannot reference variables
+ * from the outer scope. Arguments are serialized via postMessage.
+ *
+ * **Trust boundary:** the function's source is evaluated in a `blob:` worker,
+ * which is equivalent to `eval()`. Only a function object is accepted — never
+ * a string, and never a function built from untrusted input.
+ *
+ * @param fn A pure function to execute in a worker thread.
+ * @returns An object with run, loading, and terminate.
+ */
+declare function workerFn<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult): UseWorkerFnReturn<TArgs, TResult>;
+interface WorkerPool<TInput, TOutput> {
+    execute(data: TInput): Promise<TOutput>;
+    terminate(): void;
+}
+/**
+ * createWorkerPool creates a pool of workers for parallel task execution.
+ *
+ * Tasks are distributed across workers using round-robin scheduling.
+ * Each worker is created from the same inline function.
+ *
+ * **Trust boundary:** as with `worker()`, the function's source is evaluated in
+ * a `blob:` worker. Only a function object is accepted, never a string.
+ *
+ * @param workerFn The function body to run inside each worker.
+ * @param poolSize Number of workers in the pool (defaults to navigator.hardwareConcurrency or 4).
+ * @returns An object with execute and terminate.
+ */
+declare function createWorkerPool<TInput = unknown, TOutput = unknown>(workerFn: (e: MessageEvent<TInput>) => void, poolSize?: number): WorkerPool<TInput, TOutput>;
+
+/**
+ * WebAssembly integration for SibuJS.
+ * Provides hooks and utilities to load, cache, and use WASM modules
+ * for performance-critical operations.
+ */
+interface WasmModuleState<T extends object = Record<string, unknown>> {
+    /** The instantiated WASM module exports, null until loaded */
+    instance: T | null;
+    /** Loading state */
+    loading: boolean;
+    /** Error if loading failed */
+    error: Error | null;
+    /** Whether the module has been loaded successfully */
+    ready: boolean;
+}
+/**
+ * Configuration for the `wasm()` reactive wrapper.
+ *
+ * Deliberately the SAME option bag as the underlying `loadWasmModule()`
+ * primitive rather than a hand-copied subset. The primitive REQUIRES an
+ * explicit origin policy for URL sources (`allowedOrigins`, or an explicit
+ * `unsafelyAllowAnyOrigin` opt-in), and the wrapper previously had no way to
+ * express one — so `wasm("/math.wasm")` could only ever reject, and the public
+ * convenience API was unusable for its documented primary use case. Extending
+ * the primitive's type keeps the two from drifting again.
+ */
+interface WasmConfig extends LoadWasmOptions {
+}
+/**
+ * Hook to load and use a WebAssembly module reactively.
+ * Returns reactive state that updates when the module loads.
+ *
+ * A URL source needs an explicit origin policy — WASM is compiled code with
+ * imports into JS memory, so fetching it from an unvetted URL is a supply-chain
+ * risk equivalent to importing a remote module (CWE-829). Pass `allowedOrigins`,
+ * or `unsafelyAllowAnyOrigin: true` to opt out deliberately. An `ArrayBuffer` /
+ * `Uint8Array` source needs neither: the bytes are already in hand.
+ *
+ * @example
+ * ```ts
+ * const math = wasm<{ add: (a: number, b: number) => number }>(
+ *   'https://cdn.example.com/math.wasm',
+ *   { allowedOrigins: ['https://cdn.example.com'] },
+ * );
+ * // In reactive context:
+ * if (math.ready()) {
+ *   const result = math.instance()!.add(1, 2);
+ * }
+ * ```
+ *
+ * @example Same-origin asset — still an explicit decision.
+ * ```ts
+ * const math = wasm('/math.wasm', { allowedOrigins: [location.origin] });
+ * ```
+ */
+declare function wasm<T extends object = Record<string, unknown>>(source: string | ArrayBuffer | Uint8Array, config?: WasmConfig): {
+    instance: () => T | null;
+    loading: () => boolean;
+    error: () => Error | null;
+    ready: () => boolean;
+    reload: () => Promise<void>;
+};
+/**
+ * Load and instantiate a WebAssembly module.
+ * Supports loading from URL, ArrayBuffer, or Uint8Array.
+ *
+ * Caching: keyed by `cacheKey` (or, for a URL source, the URL itself). A keyed
+ * load is memoized as a **singleton instance** — every caller with the same key
+ * receives the *same* `WebAssembly.Instance`, which shares one linear memory and
+ * mutable globals. This is intentional (load-once / reuse), but it means callers
+ * that need isolated state must use distinct cache keys, or pass a non-URL source
+ * with no `cacheKey` (which instantiates fresh every call). Compiled modules are
+ * immutable and always safe to share.
+ */
+interface LoadWasmOptions {
+    imports?: WebAssembly.Imports;
+    cacheKey?: string;
+    allowedOrigins?: string[];
+    /** Required when source is a URL and allowedOrigins is empty. WASM is
+     *  compiled code with imports into JS memory — fetching from any URL is
+     *  a supply-chain risk equivalent to remote module import (CWE-829). */
+    unsafelyAllowAnyOrigin?: boolean;
+}
+/**
+ * Load and instantiate a WebAssembly module — **positional/legacy form**.
+ *
+ * The second parameter is always `WebAssembly.Imports` and the third is always
+ * the cache key. There is no structural guessing, so a module namespace legally
+ * named `imports` or `cacheKey` is passed through unharmed.
+ *
+ * It previously accepted `WebAssembly.Imports | LoadWasmOptions` and decided
+ * between them at runtime by probing for `allowedOrigins` /
+ * `unsafelyAllowAnyOrigin`. That discriminator was unsound in both directions:
+ * an options bag carrying only `imports`/`cacheKey` was read as an import
+ * namespace (so `cacheKey` was dropped and the documented keyed-singleton
+ * guarantee silently did not hold), while a genuine namespace *named*
+ * `allowedOrigins` would have been read as options. No structural test can
+ * separate the two, because both are plain objects with caller-chosen keys — so
+ * the union was removed rather than re-guessed.
+ *
+ * For anything beyond imports and a cache key — notably the origin policy a URL
+ * source requires — use {@link loadWasmModuleWithOptions}.
+ *
+ * @see loadWasmModuleWithOptions
+ */
+declare function loadWasmModule(source: string | ArrayBuffer | Uint8Array, imports?: WebAssembly.Imports, cacheKey?: string): Promise<WebAssembly.Instance>;
+/**
+ * Load and instantiate a WebAssembly module — **options form**.
+ *
+ * Unambiguous by construction: options live in their own parameter, so a WASM
+ * module namespace named `imports`, `cacheKey`, or `allowedOrigins` is just a
+ * namespace and nothing has to be inferred from object shape.
+ *
+ * This is the form to use for a URL source, since the origin policy
+ * (`allowedOrigins`, or an explicit `unsafelyAllowAnyOrigin`) can only be
+ * expressed here.
+ *
+ * @example
+ * ```ts
+ * const instance = await loadWasmModuleWithOptions("https://cdn.example.com/math.wasm", {
+ *   allowedOrigins: ["https://cdn.example.com"],
+ *   imports: { env: { log: console.log } },
+ *   cacheKey: "math",
+ * });
+ * ```
+ */
+declare function loadWasmModuleWithOptions(source: string | ArrayBuffer | Uint8Array, opts?: LoadWasmOptions): Promise<WebAssembly.Instance>;
+/**
+ * Preload and compile a WASM module without instantiating it.
+ * The compiled module is cached for instant instantiation later.
+ */
+declare function preloadWasm(url: string, options?: {
+    allowedOrigins?: string[];
+    unsafelyAllowAnyOrigin?: boolean;
+}): Promise<void>;
+/**
+ * Create a type-safe bridge to a WASM module with automatic memory management.
+ * Provides helpers for passing strings and arrays between JS and WASM.
+ */
+declare function createWasmBridge<T extends object>(instance: WebAssembly.Instance): {
+    exports: T;
+    memory: WebAssembly.Memory;
+    /** Allocate bytes in WASM memory (requires WASM to export malloc) */
+    alloc: (size: number) => number;
+    /** Free allocated memory (requires WASM to export free) */
+    free: (ptr: number) => void;
+    /** Write a string to WASM memory, returns pointer */
+    writeString: (str: string) => {
+        ptr: number;
+        len: number;
+    };
+    /** Read a string from WASM memory */
+    readString: (ptr: number, len: number) => string;
+    /** Write a typed array to WASM memory, returns pointer */
+    writeArray: (arr: ArrayLike<number>) => {
+        ptr: number;
+        len: number;
+    };
+    /** Read a Float64Array from WASM memory */
+    readF64Array: (ptr: number, len: number) => Float64Array;
+};
+/**
+ * Invalidate the module, instance, and in-flight WASM cache generations.
+ *
+ * CONTRACT: work already started may still resolve to the callers that started
+ * it, but must never repopulate the caches after the clear. A load in flight
+ * across this call therefore still returns its instance to whoever awaited it,
+ * while the cache stays empty and the next load for that key compiles and
+ * instantiates afresh.
+ *
+ * This is an invalidation BARRIER, not a `Map.clear()`: emptying the maps alone
+ * would let the invalidated work write its results straight back in.
+ */
+declare function clearWasmCache(): void;
+/**
+ * Check if a WASM module is cached.
+ */
+declare function isWasmCached(key: string): boolean;
+
+interface MicroAppConfig {
+    /** Unique name for this micro-frontend instance */
+    name: string;
+    /** Optional host element to mount into. Defaults to a new div. */
+    container?: HTMLElement;
+    /** If true, use Shadow DOM for style isolation */
+    shadow?: boolean;
+}
+interface MicroApp {
+    /** Mount a component into this micro-app container */
+    mount(component: () => HTMLElement): void;
+    /** Unmount the currently rendered component and clean up */
+    unmount(): void;
+    /** The outer host element */
+    element: HTMLElement;
+}
+interface SharedScope<T extends object> {
+    /** Get the current value for a key */
+    get<K extends keyof T>(key: K): T[K];
+    /** Set a value for a key, notifying all subscribers */
+    set<K extends keyof T>(key: K, value: T[K]): void;
+    /** Subscribe to changes on a specific key. Returns an unsubscribe function. */
+    subscribe<K extends keyof T>(key: K, callback: (value: T[K]) => void): () => void;
+}
+/**
+ * Creates an isolated micro-frontend container.
+ *
+ * Each micro-app gets its own DOM boundary. When `shadow: true` is set the
+ * component renders inside a Shadow DOM root so its styles are fully isolated
+ * from the host page.
+ *
+ * @example
+ * ```ts
+ * const app = createMicroApp({ name: "widget", shadow: true });
+ * document.body.appendChild(app.element);
+ *
+ * app.mount(() => div("Hello from micro-app!"));
+ *
+ * // Later, tear it down:
+ * app.unmount();
+ * ```
+ */
+declare function createMicroApp(config: MicroAppConfig): MicroApp;
+/**
+ * Dynamically load a remote ES module by URL.
+ *
+ * Modules are cached by URL so repeated calls with the same URL return the
+ * same promise without issuing another network request.
+ *
+ * An origin policy is REQUIRED: importing a remote module is remote code
+ * execution, so the call is refused unless you either restrict it with
+ * `allowedOrigins` or opt out deliberately with `unsafelyAllowAnyOrigin`
+ * (CWE-829).
+ *
+ * @example
+ * ```ts
+ * const charts = await loadRemoteModule("https://cdn.example.com/charts.js", {
+ *   allowedOrigins: ["https://cdn.example.com"],
+ * });
+ * const el = charts.BarChart({ data: [1, 2, 3] });
+ * ```
+ */
+interface LoadRemoteModuleOptions {
+    allowedOrigins?: string[];
+    /** Required when allowedOrigins is empty. Forces a deliberate decision
+     *  to import code from any URL — equivalent to remote eval (CWE-829). */
+    unsafelyAllowAnyOrigin?: boolean;
+}
+declare function loadRemoteModule(url: string, optionsOrAllowedOrigins?: string[] | LoadRemoteModuleOptions): Promise<unknown>;
+/**
+ * Loads the remote module whose `default` export is the component. Its root may
+ * be any `Element` — an SVG root included — using the public `Component` type
+ * rather than a private `() => HTMLElement` that forced a cast.
+ */
+type RemoteLoader<R extends Element = HTMLElement> = () => Promise<{
+    default: Component<void, R>;
+}>;
+/**
+ * Register a remote component that loads on demand.
+ *
+ * Returns a component factory function. On first call it shows a loading
+ * placeholder, fetches the remote module, then swaps in the real component.
+ * Subsequent calls render instantly from the cached module.
+ *
+ * The load is owner-scoped: if the container is disposed before the module
+ * arrives, the module is still cached (it is shared and expensive to fetch) but
+ * the component is NOT instantiated and nothing is written into the dead
+ * container.
+ *
+ * @example
+ * ```ts
+ * const RemoteHeader = defineRemoteComponent(
+ *   "remote-header",
+ *   () =>
+ *     loadRemoteModule("https://cdn.example.com/header.js", {
+ *       allowedOrigins: ["https://cdn.example.com"],
+ *     })
+ * );
+ *
+ * // Use it like any local component
+ * document.body.appendChild(RemoteHeader());
+ * ```
+ */
+declare function defineRemoteComponent<R extends Element = HTMLElement>(name: string, loader: RemoteLoader<R>): Component<void, R | HTMLElement>;
+/**
+ * Create a shared state scope that enables communication between independent
+ * micro-frontend instances.
+ *
+ * Each key in the scope can be read, written, and subscribed to independently.
+ * This is intentionally kept simpler than a full global store so micro-apps
+ * can share data with minimal coupling.
+ *
+ * @example
+ * ```ts
+ * const shared = createSharedScope({ user: null, theme: "light" });
+ *
+ * // Micro-app A sets a value
+ * shared.set("user", { name: "Alice" });
+ *
+ * // Micro-app B subscribes to changes
+ * const unsub = shared.subscribe("user", (user) => {
+ *   console.log("User changed:", user);
+ * });
+ *
+ * // Later
+ * unsub();
+ * ```
+ */
+declare function createSharedScope<T extends object>(initialState: T): SharedScope<T>;
+
+interface ServiceWorkerState {
+    registration: () => ServiceWorkerRegistration | null;
+    isReady: () => boolean;
+    isUpdateAvailable: () => boolean;
+    error: () => Error | null;
+    update: () => Promise<void>;
+    unregister: () => Promise<boolean>;
+}
+/**
+ * serviceWorker registers and manages a service worker.
+ *
+ * TRUST BOUNDARY: `scriptUrl` is CODE. A service worker runs with authority
+ * over every page in its scope and persists across reloads, so this is the
+ * strongest code-loading primitive in the framework. The browser enforces
+ * same-origin, a secure context and a JavaScript MIME type — it does NOT
+ * protect against a same-origin URL that serves attacker-influenced content
+ * (a JSONP endpoint, an upload directory). Pass only a literal path to a worker
+ * script you ship; never a value derived from the URL, storage or an API
+ * response.
+ *
+ * LIFECYCLE CONTRACT
+ * ------------------
+ * Registration is asynchronous and `unregister()` can be called at any point
+ * during it, so this tracks four distinct situations rather than one boolean:
+ *
+ *   registering      register() in flight, nothing to unregister yet
+ *   active           registration adopted, listeners attached
+ *   unregister asked requested before the registration resolved — the arriving
+ *                    registration is unregistered rather than adopted, so the
+ *                    browser never keeps a worker SibuJS has forgotten
+ *   unregistered     terminal, and only entered once unregister() actually
+ *                    RETURNED TRUE
+ *
+ * The last point is the important one. `ServiceWorkerRegistration.unregister()`
+ * returns `false` when the browser declined — the worker is still installed and
+ * still controlling pages. Treating that as teardown (detaching listeners,
+ * dropping the registration) left the wrapper permanently blind to a worker
+ * that was very much alive: no update tracking, no registration, no way back.
+ * A failed unregister therefore changes nothing.
+ */
+declare function serviceWorker(scriptUrl: string, options?: RegistrationOptions): ServiceWorkerState;
+
+interface SSGOptions {
+    routes: string[];
+    renderFn: (path: string) => Promise<string>;
+    outDir?: string;
+}
+interface SSGResult {
+    pages: Array<{
+        path: string;
+        html: string;
+    }>;
+    errors: Array<{
+        path: string;
+        error: Error;
+    }>;
+}
+/**
+ * Generate a static site by iterating over routes and collecting rendered HTML.
+ * This is a pure async function — it does NOT write files, only returns results.
+ */
+declare function generateStaticSite(options: SSGOptions): Promise<SSGResult>;
+
+interface ISROptions<T> {
+    revalidateAfter: number;
+    fetcher: (ctx?: {
+        signal: AbortSignal;
+    }) => Promise<T>;
+    initialData?: T;
+}
+/**
+ * Creates an Incremental Static Regeneration (ISR) resource.
+ * Data is fetched initially, then automatically revalidated once it goes stale.
+ *
+ * `isStale()` is a reactive signal: it flips to `true` when `revalidateAfter`
+ * elapses since the last successful fetch (effects re-run at that moment), stays
+ * `true` while a revalidation is pending or after one fails, and returns to
+ * `false` when a revalidation succeeds.
+ *
+ * `revalidate()` called while a revalidation is running joins it instead of
+ * starting another: the fetcher runs once, and every caller's promise settles
+ * — resolving, or rejecting with the same error — when that fetch does.
+ *
+ * @throws RangeError when `revalidateAfter` is not a positive finite number.
+ */
+declare function createISR<T>(options: ISROptions<T>): {
+    data: () => T | undefined;
+    isStale: () => boolean;
+    revalidate: () => Promise<void>;
+    dispose: () => void;
+};
+
+type ActionFn<T = unknown> = (data: FormData | Record<string, unknown>) => Promise<T>;
+interface ActionResult<T> {
+    data: () => T | undefined;
+    error: () => Error | undefined;
+    loading: () => boolean;
+    submit: (data: FormData | Record<string, unknown>) => Promise<T>;
+}
+/**
+ * Creates a managed action for handling POST/PUT/DELETE-style mutations.
+ * Provides reactive loading, error, and data state via signal.
+ * State updates are batched to avoid redundant notifications.
+ */
+declare function createAction<T>(actionFn: ActionFn<T>): ActionResult<T>;
+
+interface ScrollRestorationOptions {
+    /**
+     * `"auto"` (default) manages history-entry identity and restores the
+     * destination on `popstate`. It tags the entry the page started on, tags each
+     * entry you announce with `onNavigation()`, saves the outgoing position, and
+     * takes over `history.scrollRestoration` so the browser does not restore in
+     * parallel.
+     *
+     * What auto mode CANNOT do is notice a `history.pushState` it was not told
+     * about — no library can, short of monkey-patching `history` globally. Entries
+     * created without `onNavigation()` carry no identity and are simply not
+     * restored (a safe no-op, not a wrong position).
+     *
+     * `"manual"` attaches no listener, claims no native restoration, and tags
+     * nothing — you call `save()` / `restore()` yourself.
+     */
+    mode?: "auto" | "manual";
+    /**
+     * Identifies the entry the user is currently on. Called once at construction
+     * to seed the current entry, and consulted as a fallback when nothing has
+     * been saved yet.
+     *
+     * Point it at whatever your app treats as a history identity — e.g.
+     * `() => router.location().key`. Pathname alone is usually wrong: `?page=2`
+     * and `#section` are distinct scroll positions to a user.
+     */
+    getKey?: () => string | null;
+    /**
+     * History-state property used to tag entries so a `popstate` can name its
+     * DESTINATION. `popstate` reports the state of the entry being restored, and
+     * that is the only reliable way to know where the user just landed.
+     */
+    stateKey?: string;
+}
+/**
+ * Manages scroll position saving and restoration keyed by route/key.
+ *
+ * AUTO MODE
+ * ---------
+ * `"auto"` previously attached a `popstate` listener that only ever called
+ * `save()` — so the documented "save/restore on popstate" behaviour was half
+ * implemented, and going Back never returned the viewport anywhere. The whole
+ * point of the feature was the half that was missing.
+ *
+ * A real restore needs to know WHICH entry the user landed on, so auto mode
+ * tags history entries with their key (`stateKey`) and the `popstate` handler
+ * reads that tag off `event.state`. On each pop it:
+ *
+ *   1. saves the position of the entry being LEFT (unless it is also the
+ *      destination — a same-key pop is not a departure, and saving there would
+ *      overwrite the stored position with the current one, destroying exactly
+ *      the value about to be restored)
+ *   2. restores the destination's saved position, if one exists
+ *
+ * An unknown or absent destination key is a safe SibuJS no-op: no guessed
+ * position is applied. Note this is not a hand-off to the browser — auto mode
+ * leases `history.scrollRestoration` to `"manual"` while active, so nothing
+ * else is restoring either. The viewport simply stays where the engine left it.
+ *
+ * WHAT "AUTO" MEANS, EXACTLY
+ * --------------------------
+ * Reacting to `popstate` automatically is not enough on its own: the handler
+ * can only restore an entry that HAS an identity, and originally nothing ever
+ * gave one to the entry the page started on. The first Back a user pressed
+ * therefore restored nothing. Auto mode now owns identity as well as reaction:
+ *
+ *   - the INITIAL entry is tagged at construction, and
+ *   - `onNavigation(key)` tags each entry the application creates.
+ *
+ * That second half is an explicit hook rather than magic, and deliberately so:
+ * a library cannot observe arbitrary `history.pushState` calls without patching
+ * `history` globally, which would surprise every other consumer of it. So the
+ * honest contract is:
+ *
+ *   > Auto mode restores any entry it was given identity for, and never guesses
+ *   > about entries it was not told about.
+ *
+ * Auto mode also leases `history.scrollRestoration = "manual"` while active, so
+ * the browser is not restoring the viewport at the same time SibuJS is. The
+ * previous value is restored when the last controller is disposed.
+ */
+declare function scrollRestoration(options?: ScrollRestorationOptions): {
+    save: (key: string) => void;
+    restore: (key: string) => void;
+    /**
+     * Tell auto mode that the application created a new history entry.
+     *
+     * Records the outgoing entry's position, tags the new entry with `key`, and
+     * makes it current. Call it immediately after your `pushState` (before any
+     * scrolling), so the position captured is the one the user is leaving.
+     */
+    onNavigation: (key: string) => void;
+    getPosition: (key: string) => {
+        x: number;
+        y: number;
+    } | undefined;
+    dispose: () => void;
+};
+
+type MiddlewareFn = (context: {
+    path: string;
+    params: Record<string, string>;
+}, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * Composes multiple middleware functions into a single middleware.
+ * Each middleware must call next() to proceed to the next one.
+ */
+declare function composeMiddleware(...fns: MiddlewareFn[]): MiddlewareFn;
+/**
+ * Creates a middleware chain with a builder API.
+ * Use `use()` to add middleware, and `run()` to execute the chain.
+ */
+declare function createMiddlewareChain(): {
+    use: (fn: MiddlewareFn) => void;
+    run: (context: {
+        path: string;
+        params: Record<string, string>;
+    }) => Promise<void>;
+};
+
+export { type ActionFn as A, preloadWasm as B, scrollRestoration as C, serviceWorker as D, setCanonical as E, setStructuredData as F, wasm as G, Head as H, type ISROptions as I, worker as J, workerFn as K, type LoadRemoteModuleOptions as L, type MicroApp as M, type SSGOptions as S, type UseWorkerFnReturn as U, type WasmConfig as W, type ActionResult as a, type LoadWasmOptions as b, type MicroAppConfig as c, type MiddlewareFn as d, type SSGResult as e, type ScrollRestorationOptions as f, type ServiceWorkerState as g, type SharedScope as h, type UseWorkerReturn as i, type WasmModuleState as j, type WorkerPool as k, clearWasmCache as l, composeMiddleware as m, createAction as n, createISR as o, createMicroApp as p, createMiddlewareChain as q, createSharedScope as r, createWasmBridge as s, createWorkerPool as t, defineRemoteComponent as u, generateStaticSite as v, isWasmCached as w, loadRemoteModule as x, loadWasmModule as y, loadWasmModuleWithOptions as z };