sibujs 4.13.1 → 4.14.0

package/dist/routeHead-DzVxPviY.d.ts

@@ -0,0 +1,995 @@
+import { C as Component$1, N as NodeChildren } from './types-CJFViL6Q.js';
+
+/**
+ * Creation scopes for adopting hydration (see docs/architecture/hydration-adopt.md).
+ *
+ * The server and the browser agree on an id for every element a builder
+ * creates. An id is a PATH, not a global counter: each directive (`when`,
+ * `match`, `each` row, reactive child, `lazy()`, `Suspense`, route outlet)
+ * opens its own scope, and an element's id is its creation index inside the
+ * scope it was built in. So a branch the server rebuilt after its data arrived,
+ * or two boundaries that resolved in a different order, still get the ids the
+ * browser's first build gives them.
+ *
+ *   App scope ""        div#0  span#1  when → scope "2."
+ *   when branch "2."    ul#2.0 each → scope "2.1."
+ *   each row "2.1._a."  li#2.1._a.0    (key "a"; key 7 → "2.1.-7.")
+ *
+ * Nothing here runs unless a server render asked for adoption markers or a
+ * browser hydration is adopting: with no current scope every hook is one
+ * comparison. The sink deciding what an id means (stamp it on the server,
+ * claim the server element in the browser) lives in `sibujs/ssr`.
+ */
+/** What a scope's elements are created through. */
+interface AdoptSink {
+    /** False once the session is over: scopes stop numbering, and nothing is claimed any more. */
+    on: boolean;
+    /** Create (server) or claim (browser) the element with `id`; `null` means "create it normally". */
+    el(tag: string, ns: string | undefined, id: string): Element | null;
+    /** The hydration session a browser sink belongs to (see `hydrationHooks`). */
+    h?: unknown;
+}
+/** A creation scope: id prefix, next index, the sink. */
+interface AdoptScope {
+    p: string;
+    n: number;
+    s: AdoptSink;
+}
+
+/**
+ * A route component. An alias of the public `Component` (props-less, any
+ * `Element` root), kept under this name so existing imports of the router's
+ * `Component` continue to work.
+ */
+type Component = Component$1<void, Element>;
+type AsyncComponent = () => Promise<Element>;
+type LazyComponent = () => Promise<{
+    default: Component;
+}>;
+type Params = Record<string, string>;
+/** Every value of every query key, in URL order: `?tag=a&tag=b` is `{ tag: ["a", "b"] }`. */
+type QueryValues = Readonly<Record<string, readonly string[]>>;
+/**
+ * The query of a navigation object. An array value repeats its key once per
+ * value, in order: `{ tag: ["a", "b"] }` is `?tag=a&tag=b`.
+ */
+type NavigationQuery = Readonly<Record<string, string | readonly string[]>>;
+interface RouteContext {
+    readonly path: string;
+    readonly params: Params;
+    /**
+     * The decoded query (`+` is a space, `%XX` is decoded). A repeated key keeps
+     * its last value here: `?tag=a&tag=b` is `{ tag: "b" }`. Read
+     * {@link RouteContext.queryAll} for every value.
+     */
+    readonly query: Params;
+    /**
+     * Every value of every query key, in URL order, with the same decoding as
+     * `query`: `?tag=a&tag=b` is `{ tag: ["a", "b"] }`. Two locations are the
+     * same route — for duplicate detection and `RouterLink` exact-active — when
+     * these match, key order aside.
+     */
+    readonly queryAll: QueryValues;
+    readonly hash: string;
+    readonly meta: RouteMeta;
+    readonly matched: RouteDef[];
+}
+type GuardResult = boolean | string | Promise<boolean | string>;
+type Guard = (to: RouteContext, from?: RouteContext) => GuardResult;
+type NavigationGuard = (to: RouteContext, from: RouteContext, next: NavigationNext) => void;
+type NavigationNext = (result?: boolean | string | Error) => void;
+type RouteMeta = Record<string, unknown>;
+interface RouteBase {
+    readonly path: string;
+    readonly name?: string;
+    readonly meta?: RouteMeta;
+    /**
+     * The document head while this route is committed: `title`, `description`,
+     * `canonical`, Open Graph (`og`) and extra `meta` entries. Values may be
+     * getters `(route) => string`, evaluated reactively. Nested records merge,
+     * the deepest winning; `createRouter({ head })` provides the defaults.
+     *
+     * The router manages the head only once some route (or the router) declares
+     * one, so an app without `head` is never touched.
+     */
+    readonly head?: RouteHead;
+    readonly children?: RouteDef[];
+    readonly beforeEnter?: Guard | Guard[];
+    readonly alias?: string | string[];
+    /**
+     * Identity of the mounted instance of this route's component.
+     *
+     * When a navigation stays on this route but the key changes, the outlet
+     * disposes the old instance (running its `onUnmount` / `onCleanup`
+     * callbacks and releasing its bindings) and mounts a fresh one — so a page
+     * that reads `route().params.id` once at setup always sees the right id.
+     *
+     * **Default:** the path params this record declares in its *own* path (and
+     * aliases). `/records/1` → `/records/2` remounts; `?tab=a` → `?tab=b` or a
+     * hash change does not. A parent layout is not remounted when only a child's
+     * param changes — the child's `Outlet()` remounts the child instead. A
+     * record with no params of its own is never remounted by a param change, and
+     * a `*` tail (`pathMatch`) is not part of the default: a catch-all keeps its
+     * instance and reads `pathMatch` reactively (`key: (r) => r.params.pathMatch`
+     * remounts per path).
+     *
+     * **Override:** return any string derived from the route. Return a constant
+     * to keep one long-lived instance across param changes (the instance must
+     * then read params reactively, e.g. `routerState().params()` or
+     * `() => route().params.id`). Include query values to also remount on a
+     * query change.
+     *
+     * Called untracked with the committed route. Ignored by `KeepAliveRoute()`,
+     * which already keeps one instance per full location.
+     *
+     * @example
+     * ```ts
+     * // Keep one instance for every record; the page reads params reactively.
+     * { path: "/records/:id", component: RecordPage, key: () => "record" }
+     * // Also remount when ?tab changes.
+     * { path: "/records/:id", component: RecordPage, key: (r) => `${r.params.id}|${r.query.tab ?? ""}` }
+     * ```
+     */
+    readonly key?: (route: RouteContext) => string;
+    /**
+     * HTTP status a server render of this route answers with. A `*` record
+     * answers 404 without it; a `redirect` record answers 302 (set `301` for a
+     * permanent move). The deepest matched record that declares one wins.
+     */
+    readonly status?: number;
+    /**
+     * How a server render treats this route (the deepest record that declares
+     * it wins; the default is to render it):
+     *
+     * - `"prerender"` — rendered at build time and on a per-request server.
+     * - `"ssr"` — rendered per request only; the build-time pre-renderer emits
+     *   the app shell plus the route's `head` for it, because its content is
+     *   per-request (a status page).
+     * - `"client"` — never rendered on a server: the shell plus the route's
+     *   `head` (a canvas designer, an admin panel). Excluded from the sitemap.
+     */
+    readonly render?: "ssr" | "prerender" | "client";
+    /**
+     * The concrete paths of a dynamic route, for the build-time pre-renderer:
+     * each entry is a params object for this record's path (`{ id: "taza" }`
+     * for `/producto/:id`) or a ready path string. May be async (read the
+     * catalog from the API at build time).
+     */
+    readonly getStaticPaths?: () => Iterable<Params | string> | Promise<Iterable<Params | string>>;
+}
+interface ComponentRoute extends RouteBase {
+    readonly component: Component;
+}
+interface AsyncRoute extends RouteBase {
+    readonly component: AsyncComponent | LazyComponent;
+}
+interface RedirectRoute extends RouteBase {
+    readonly redirect: string | ((to: RouteContext) => string);
+}
+/**
+ * A route whose component is loaded on first visit via a dynamic
+ * `import()`. This is the ergonomic shorthand for
+ * `{ component: lazy(() => import("./Page")) }`.
+ *
+ * The loader must return a module with a `default` Component export.
+ */
+interface LazyRoute extends RouteBase {
+    readonly lazy: () => Promise<{
+        default: Component;
+    }>;
+}
+type RouteDef = ComponentRoute | AsyncRoute | RedirectRoute | LazyRoute;
+interface RouterOptions {
+    /**
+     * `"history"` (default) and `"hash"` read and write the browser location.
+     * `"memory"` keeps the location in the router itself: it starts at `url`
+     * and never touches `window`, `history` or `location`. Created inside a
+     * server request scope (`runInSSRContext`, `renderRoute`), a memory router
+     * belongs to that request only, so concurrent renders each have their own.
+     */
+    readonly mode?: "history" | "hash" | "memory";
+    /**
+     * Initial location of a `"memory"` router (`"/cotizar?servicio=dtf"`).
+     * Default `"/"`. It is the REQUEST URL, like the browser's location: with a
+     * `base`, a path under it (`/app/cotizar`, `/app`, `/app/`) has the base
+     * stripped at a segment boundary, the query and hash kept; a path not under
+     * it (`/application`) is taken as it is. Navigation targets (`navigate()`,
+     * links, redirects) are application paths, without the base, in every mode.
+     */
+    readonly url?: string;
+    /**
+     * `"strict"` (default): `/cotizar/` and `/cotizar` are different paths.
+     * `"ignore"`: a trailing slash is dropped before matching, so `/cotizar/` is
+     * the `/cotizar` route — what a static server serving `cotizar/index.html`
+     * at `/cotizar/` (FastAPI `StaticFiles`, nginx, S3) needs.
+     */
+    readonly trailingSlash?: "strict" | "ignore";
+    readonly base?: string;
+    readonly linkActiveClass?: string;
+    readonly linkExactActiveClass?: string;
+    readonly fallback?: boolean;
+    /**
+     * Scroll position to restore after a navigation commits.
+     *
+     * A **browser-only, post-navigation side effect**:
+     *
+     * - In a runtime without the required scrolling primitives
+     *   (`requestAnimationFrame` and `window.scrollTo`) the hook is **not invoked
+     *   at all** — it is browser code, and its result would be discarded anyway.
+     * - It runs *after* the route and history have committed. An exception it
+     *   throws is reported to the console but never retroactively fails an
+     *   already-committed navigation: `NavigationResult.success` stays `true` and
+     *   `currentRoute` stays authoritative.
+     * - Returning a falsy value means "do not scroll" and is not an error.
+     */
+    readonly scrollBehavior?: ScrollBehavior;
+    readonly guardTimeout?: number;
+    readonly cacheSize?: number;
+    readonly errorRetryDelay?: number;
+    readonly preloadStrategy?: "none" | "hover" | "visible";
+    /**
+     * Enable KeepAlive caching for route components.
+     * - `true` — cache all routes
+     * - string[] — cache only named routes matching these names
+     * - number — cache all routes with this max cache size
+     */
+    readonly keepAlive?: boolean | string[] | number;
+    /**
+     * Head defaults for every route, plus `titleTemplate`. Declaring it (or a
+     * `head` on any route) makes the router own `document.title` and the
+     * description / canonical / Open Graph tags; see {@link RouteBase.head}.
+     */
+    readonly head?: RouterHeadOptions;
+}
+type ScrollBehavior = (to: RouteContext, from: RouteContext, savedPosition: ScrollPosition | null) => ScrollPosition | null;
+interface ScrollPosition {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Why a navigation failed, at a finer grain than `type`.
+ *
+ * `type: "aborted"` alone cannot tell a caller whether the user was denied
+ * access, whether they simply clicked a newer link, or whether the app tore the
+ * router down — three situations that call for very different handling (show a
+ * message / stay silent / stay silent). `reason` disambiguates them without
+ * changing the existing `type` values, so code branching on `type` keeps
+ * working unchanged.
+ *
+ * - `guard` — a navigation guard returned `false`.
+ * - `superseded` — a newer navigation started before this one could commit.
+ *   Expected during rapid navigation; normally not surfaced to users.
+ * - `router-destroyed` — the router was destroyed while this navigation was in
+ *   flight.
+ * - `redirect-loop` — redirect resolution exceeded the maximum hop count.
+ * - `unsafe-target` — the target or a redirect used a blocked URI scheme, or was
+ *   an absolute/protocol-relative URL (open-redirect protection).
+ * - `duplicate` — the target is identical to the current route.
+ * - `error` — an unexpected error escaped the navigation pipeline.
+ */
+type NavigationFailureReason = "guard" | "superseded" | "router-destroyed" | "redirect-loop" | "unsafe-target" | "duplicate" | "error";
+interface NavigationFailure {
+    readonly type: "aborted" | "cancelled" | "duplicated" | "timeout";
+    /**
+     * Finer-grained cause. Additive — existing checks on `type` are unaffected.
+     */
+    readonly reason?: NavigationFailureReason;
+    readonly from: RouteContext;
+    readonly to: RouteContext;
+    readonly error?: Error;
+}
+type NavigationResult = {
+    success: true;
+    route: RouteContext;
+} | {
+    success: false;
+    type: NavigationFailure["type"];
+    /** Mirrors `failure.reason`; see {@link NavigationFailureReason}. */
+    reason?: NavigationFailureReason;
+    failure: NavigationFailure;
+};
+type NavigationTarget = string | {
+    path?: string;
+    name?: string;
+    params?: Params;
+    query?: NavigationQuery;
+    hash?: string;
+};
+/**
+ * Component loader with caching and error recovery
+ */
+/**
+ * How the router will produce an instance of a route's component.
+ *
+ * Deliberately never holds an `Element`: an instance produced by one invocation
+ * must never become a reusable factory. (LOAD-002)
+ *
+ * The two kinds are structural, not provisional:
+ *
+ * - `factory` — invoke once per instance, only when an instance is needed.
+ *   Everything unbranded lands here: synchronous, `async`, and
+ *   Promise-returning component factories alike.
+ * - `deferred` — an **explicitly branded** `lazy()` module loader. This is the
+ *   only kind preload may execute. (LOAD-004)
+ */
+type RoutePlan = {
+    kind: "factory";
+    component: Component;
+} | {
+    kind: "deferred";
+    load: AsyncComponent | LazyComponent;
+};
+declare class SibuRouter {
+    private options;
+    private matcher;
+    private guards;
+    private loader;
+    private navigator;
+    private currentRouteGetter;
+    private currentRouteSetter;
+    private isReadyGetter;
+    private isReadySetter;
+    private cleanup;
+    private destroyed;
+    private navEpoch;
+    private headController;
+    private serverHeadRoute;
+    private withdrawServerHead;
+    private memoryLocation;
+    /**
+     * What the initial navigation did, for a server render's HTTP status: the
+     * result, and the status of the first redirect hop it took (a `redirect`
+     * record's `status`, 302 by default; 302 for a guard redirect).
+     * @internal
+     */
+    initialOutcome: {
+        result: NavigationResult | null;
+        redirectStatus: number | null;
+        /** Who redirected: a `redirect` record (the same for every visitor) or a guard (visitor-dependent). */
+        redirectBy: "route" | "guard" | null;
+    };
+    private readonly readyPromise;
+    private resolveReady;
+    private loadedPromise;
+    constructor(routes: RouteDef[], options?: RouterOptions);
+    private initialize;
+    /** Load the component of every record the current route matched, without instantiating any. */
+    private preloadMatched;
+    /** Settles once the initial navigation committed or failed (before component loads). @internal */
+    whenNavigated(): Promise<void>;
+    /** Settles after the initial navigation and its component loads; see `routerReady()`. */
+    whenReady(): Promise<void>;
+    private createInitialRoute;
+    private handleLocationChange;
+    private getCurrentPath;
+    private createRouteContext;
+    navigate(to: NavigationTarget, options?: {
+        replace?: boolean;
+        state?: unknown;
+        skipHistory?: boolean;
+        initialResolution?: boolean;
+    }): Promise<NavigationResult>;
+    private static readonly MAX_REDIRECT_DEPTH;
+    private performNavigation;
+    private updateHead;
+    private resolvePath;
+    private isSameRoute;
+    private updateHistory;
+    /**
+     * Apply the configured `scrollBehavior`, if the runtime can actually scroll.
+     *
+     * This runs *after* the route has been committed, so an exception here does
+     * not merely skip scrolling — it propagates out of `navigateInternal` and the
+     * navigation is reported as `success: false` while the route state says it
+     * succeeded. In a DOM-less runtime the bare `requestAnimationFrame` did
+     * exactly that: a legal `scrollBehavior` option made every navigation report
+     * failure under SSR and in memory-router-style tests. (MEM-001)
+     *
+     * Policy A, consistent with the history write in `updateHistory()` (NODE-001):
+     * the route still commits, and only the browser-only side effect is skipped.
+     *
+     * Both primitives are probed, not just `window` — `requestAnimationFrame` and
+     * `scrollTo` can be missing independently (jsdom without a rAF polyfill, a
+     * partial DOM shim). `requestAnimationFrame` is invoked as a method on the
+     * global object rather than through a detached reference, since browsers
+     * reject a bare call with "Illegal invocation".
+     */
+    private handleScrollBehavior;
+    /**
+     * Resolve how this route's component will be produced, without instantiating
+     * anything. Pair with {@link instantiateComponent} at the commit boundary.
+     */
+    loadPlan(route: RouteDef, routePath: string): Promise<RoutePlan>;
+    /**
+     * Create exactly one real instance from an already-resolved plan. With a
+     * `scope`, the factory runs in it (see `RouteScope`).
+     */
+    instantiateComponent(plan: RoutePlan, route: RouteDef, routePath: string, scope?: RouteScope): Promise<Element>;
+    /** Resolve a route's module/factory without creating any component instance. */
+    preloadPlan(route: RouteDef, routePath: string): Promise<void>;
+    beforeEach(guard: NavigationGuard): () => void;
+    beforeResolve(guard: NavigationGuard): () => void;
+    afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
+    push(to: NavigationTarget): Promise<NavigationResult>;
+    replace(to: NavigationTarget): Promise<NavigationResult>;
+    go(delta: number): void;
+    back(): void;
+    forward(): void;
+    get currentRoute(): RouteContext;
+    get isReady(): boolean;
+    /** @internal Navigation generation — see `navEpoch`. Not a public API. */
+    get navigationEpoch(): number;
+    get isNavigating(): boolean;
+    destroy(): void;
+    clearCache(): void;
+    clearErrorCache(): void;
+    updateRoutes(routes: RouteDef[]): void;
+    /**
+     * Add a route dynamically at runtime.
+     */
+    addRoute(route: RouteDef, parentPath?: string): void;
+    /**
+     * Remove a route by path.
+     */
+    removeRoute(path: string): void;
+    /**
+     * Get the reactive route getter for tracking.
+     */
+    get routeGetter(): () => RouteContext;
+}
+/**
+ * Create the global router and make it the one `route()`, `navigate()` and
+ * `RouterLink` talk to. Any previously created router is destroyed first.
+ *
+ * @param routesOrOptions Either the route table, or the options object when
+ * routes are supplied later via {@link setRoutes}.
+ * @param options Router options when the first argument is the route table.
+ * @returns The created router instance.
+ */
+declare function createRouter(routesOrOptions: RouteDef[] | RouterOptions, options?: RouterOptions): SibuRouter;
+/**
+ * Set routes on the global router (replaces existing routes).
+ */
+declare function setRoutes(routes: RouteDef[]): void;
+/**
+ * The route one mounted route instance was committed with.
+ *
+ * A navigation commits the router's route first; the outlet swaps the
+ * component afterwards — a microtask later for a synchronous page, a whole
+ * chunk download later for a lazy one. If route instances read the
+ * router-global route, the outgoing page re-runs its effects against the
+ * INCOMING route's params in that window, and its teardown sees them too.
+ *
+ * So each instance reads its own scope instead. Outlets create one per
+ * instance, run the component factory in it (an owner scope, see
+ * reactivity/track-core.ts, so every computation the page creates — now or
+ * later, through its directives — inherits it), and then:
+ *
+ * - an instance the outlet KEEPS across a navigation (same record and instance
+ *   key: a query/hash-only change, or a layout whose child changed) is handed
+ *   the new route — it follows the navigation, as before;
+ * - an instance being REPLACED is never updated: it keeps observing its own
+ *   route until it is disposed, and its teardown runs in its scope;
+ * - a KeepAlive view keeps its route while cached and gets the new route when
+ *   it is shown again.
+ *
+ * Once the instance is disposed the scope is released: a computation that
+ * outlived it (an app-lifetime derived that happened to be created while the
+ * page rendered) is not the page's, and falls back to the router-global route.
+ */
+declare class RouteScope {
+    /** Creation scope the instance is built in (adopting hydration); see `adoptScope`. */
+    adopt: AdoptScope | null;
+    private readonly get;
+    private readonly set;
+    private released;
+    constructor(route: RouteContext);
+    /** The instance's route, or `null` once released. Reactive. */
+    read(): RouteContext | null;
+    /** Hand a kept instance the route of the navigation that kept it. */
+    update(route: RouteContext): void;
+    /**
+     * Called when the instance is disposed. The switch to "no scope" is
+     * published a microtask later, once the whole dispose has finished: a
+     * teardown the instance registered after this one (an `onMount` effect, say)
+     * may still be alive at this point, and must not re-run against the
+     * router-global route on its way out.
+     */
+    release(): void;
+}
+/**
+ * Read the current route as a plain snapshot.
+ *
+ * Reading it once in a route component's setup is safe: when a navigation
+ * changes that route's own params, the outlet mounts a fresh instance (see
+ * `RouteBase.key`). Inside a getter — `() => route().params.id` — the read is
+ * reactive, which is what a long-lived layout or a constant-`key` route needs.
+ *
+ * Inside a route instance (anything its component creates, and any effect,
+ * derived or binding created from there) this is the route THAT INSTANCE was
+ * committed with. An instance the outlet keeps across a navigation follows it;
+ * an instance being replaced keeps its own route until it is disposed, so its
+ * effects and teardown never observe the next page's params. Everywhere else
+ * it is the router's current route.
+ *
+ * @returns The active {@link RouteContext} (path, params, query, hash).
+ * @throws If no router has been created yet.
+ */
+declare function route(): RouteContext;
+/**
+ * Handle onto the global router's navigation surface.
+ *
+ * @returns An object exposing the current route plus `push`, `replace`, `go`,
+ * `back`, `forward` and the three guard registrars.
+ * @throws If no router has been created yet.
+ */
+declare function router(): {
+    currentRoute: RouteContext;
+    isReady: boolean;
+    isNavigating: boolean;
+    push: (to: NavigationTarget) => Promise<NavigationResult> | undefined;
+    replace: (to: NavigationTarget) => Promise<NavigationResult> | undefined;
+    go: (delta: number) => void | undefined;
+    back: () => void | undefined;
+    forward: () => void | undefined;
+    beforeEach: (guard: NavigationGuard) => (() => void) | undefined;
+    beforeResolve: (guard: NavigationGuard) => (() => void) | undefined;
+    afterEach: (hook: (to: RouteContext, from: RouteContext) => void) => (() => void) | undefined;
+};
+/**
+ * Resolves once the router has resolved the page's initial location AND loaded
+ * the components that location matched (lazy route chunks included).
+ *
+ * Await it before `hydrate()` on a pre-rendered page: the client tree is then
+ * built with every route component already loaded, so the outlet renders in
+ * the same task and the swap from pre-rendered markup shows no empty frame.
+ * Also resolves if the initial navigation fails or the router is destroyed.
+ *
+ * @returns A promise that never rejects.
+ * @throws If no router has been created yet.
+ *
+ * @example
+ * ```ts
+ * createRouter(routes, { mode: "history" });
+ * await routerReady();
+ * hydrate(App, document.getElementById("app")!);
+ * ```
+ */
+declare function routerReady(): Promise<void>;
+/**
+ * Navigate to a target, running every registered guard.
+ *
+ * @param to Path string or location descriptor.
+ * @param options `replace` swaps the current history entry instead of pushing;
+ * `state` is stored on the history entry.
+ * @returns A promise for the {@link NavigationResult} — resolved even when a
+ * guard cancels, so the outcome must be inspected rather than assumed.
+ * @throws If no router has been created yet.
+ */
+declare function navigate(to: NavigationTarget, options?: {
+    replace?: boolean;
+    state?: unknown;
+}): Promise<NavigationResult>;
+/**
+ * Navigate by pushing a new history entry.
+ *
+ * @param to Path string or location descriptor.
+ * @returns A promise for the {@link NavigationResult}.
+ */
+declare function push(to: NavigationTarget): Promise<NavigationResult>;
+/**
+ * Navigate by replacing the current history entry.
+ *
+ * @param to Path string or location descriptor.
+ * @returns A promise for the {@link NavigationResult}.
+ */
+declare function replace(to: NavigationTarget): Promise<NavigationResult>;
+/**
+ * Move through history by a relative offset, as `history.go` does.
+ *
+ * @param delta Number of entries to move; negative goes back.
+ * @returns Nothing — history moves asynchronously, so nothing is awaited here.
+ */
+declare function go(delta: number): void;
+/** Go back one history entry. Equivalent to `go(-1)`. */
+declare function back(): void;
+/** Go forward one history entry. Equivalent to `go(1)`. */
+declare function forward(): void;
+/**
+ * Register a guard that runs before every navigation is confirmed.
+ *
+ * @param guard Called with the target and current routes; return `false` to
+ * cancel, or a target to redirect.
+ * @returns An unregister function.
+ */
+declare function beforeEach(guard: NavigationGuard): () => void;
+/**
+ * Register a guard that runs after `beforeEach` and after async components have
+ * resolved, but before the route commits.
+ *
+ * @param guard Called with the target and current routes.
+ * @returns An unregister function.
+ */
+declare function beforeResolve(guard: NavigationGuard): () => void;
+/**
+ * Register a hook that runs after every confirmed navigation. It cannot cancel
+ * or redirect — by the time it runs the route has already committed.
+ *
+ * @param hook Called with the new and previous routes.
+ * @returns An unregister function.
+ */
+declare function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
+/**
+ * The route outlet: renders whichever component matches the current route, and
+ * swaps it when the top-level matched record or its instance key changes. By
+ * default the key is that record's own path params, so `/records/1` →
+ * `/records/2` mounts a fresh instance while a query- or hash-only change keeps
+ * the current one (see `RouteBase.key`).
+ *
+ * @returns A Comment anchor that manages the matched component. Like every
+ * factory here it hands back a live node the caller can insert directly.
+ *
+ * TRAP — a navigation REBUILDS the outlet's subtree, so focus and selection
+ * inside the outgoing route are discarded. The runtime restores focus when the
+ * incoming route contains an element with the same `id`, `name` or
+ * `data-focus-key`, and warns in dev when it cannot.
+ */
+declare function Route(): Node;
+/**
+ * A route outlet that caches rendered components using KeepAlive.
+ * Routes are preserved in the DOM cache so signals, form state, and scroll
+ * position survive navigation.
+ *
+ * Uses the `keepAlive` option from RouterOptions if set, or accepts
+ * explicit options.
+ *
+ * ## Cache identity
+ *
+ * A cached view is keyed by the **full location** — path + query + hash — so
+ * `/search?q=a`, `/search?q=b`, and `/docs#one` are three distinct cached views.
+ * Keying on `route.path` alone would serve one query's cached DOM and state for
+ * another.
+ *
+ * ## Reuse and disposal
+ *
+ * | Event | Effect on a cached view |
+ * |---|---|
+ * | navigated away from | detached, kept in cache, **not** disposed |
+ * | navigated back to | the same node is re-attached — no remount |
+ * | evicted past `max` (LRU) | disposed and dropped |
+ * | excluded by `include` | never cached; disposed on navigation away |
+ * | outlet disposed | whole cache disposed and cleared |
+ *
+ * ## Cache identity is not async ownership
+ *
+ * The cache key answers *"which cached view is this?"*. It never answers *"may
+ * this async completion still commit?"* — that is what the update generation is
+ * for, because `same route value !== same navigation generation`. See
+ * `docs/architecture/router.md`.
+ *
+ * @param options Optional: override the router-level keepAlive setting
+ *
+ * @example
+ * ```ts
+ * // Cache all routes (max 10)
+ * createRouter(routes, { keepAlive: 10 });
+ * mount(() => div([nav, KeepAliveRoute()]), root);
+ *
+ * // Or cache specific routes by name
+ * createRouter(routes, { keepAlive: ["dashboard", "settings"] });
+ * mount(() => div([nav, KeepAliveRoute()]), root);
+ *
+ * // Or override per-outlet
+ * KeepAliveRoute({ max: 5, include: ["dashboard"] })
+ * ```
+ */
+declare function KeepAliveRoute(options?: {
+    max?: number;
+    include?: string[];
+}): Node;
+declare function RouterLink(props: {
+    to: NavigationTarget;
+    replace?: boolean;
+    activeClass?: string;
+    exactActiveClass?: string;
+    /** @deprecated Pass children positionally: `RouterLink(props, children)`. */
+    nodes?: NodeChildren;
+    target?: string;
+    rel?: string;
+    [key: string]: unknown;
+}, children?: NodeChildren): HTMLAnchorElement;
+/**
+ * Async boundary for code-split / deferred content.
+ *
+ * **Ownership contract.** The boundary owns every node it creates or installs.
+ * A node that leaves the boundary — replaced by resolved content, or dropped on
+ * teardown — is lifecycle-disposed exactly once. Native detachment alone is not
+ * cleanup: a detached subtree keeps its effects, listeners and registered
+ * disposers alive, firing against DOM nobody can see. (SUS-001)
+ *
+ * **Async completion grants no commit permission.** A resolution that arrives
+ * after the boundary was torn down, or after a newer generation superseded it,
+ * may never insert into the DOM. Because the promise typically resolves with an
+ * *already constructed* Element — whose effects and listeners were created
+ * before the boundary discovered it lost ownership — the stale result is
+ * disposed rather than merely dropped. (SUS-002)
+ *
+ * The boundary is **single-shot**: `props.nodes()` is invoked exactly once, so
+ * only one async generation is reachable in practice. The generation token is
+ * kept anyway because teardown must be able to invalidate the in-flight one, and
+ * because ownership is the correct primitive to express that with.
+ */
+declare function Suspense(props: {
+    /** Shown while `nodes` is pending. An element, or a function returning one. */
+    fallback?: (() => HTMLElement) | HTMLElement;
+    /**
+     * The content. May be an element, or any thenable resolving to one —
+     * `PromiseLike`, not `Promise`, because a promise from another realm or a
+     * custom thenable is awaited just the same. The previous type admitted only
+     * `Promise`, so the very values the runtime was fixed to handle still had to
+     * be cast at the call site.
+     */
+    nodes: () => HTMLElement | PromiseLike<HTMLElement>;
+}): Node;
+/**
+ * Creates a lazy-loaded component.
+ * Marks the function with a symbol so the router can detect it reliably
+ * (no AsyncFunction heuristic needed).
+ */
+declare function lazy(importFn: () => Promise<{
+    default: Component;
+}>): LazyComponent;
+/**
+ * Preloads a route component
+ */
+declare function preloadRoute(to: NavigationTarget): Promise<void>;
+/**
+ * Validates if a route exists
+ */
+/**
+ * Current navigation generation for the active router, or `-1` when no router
+ * exists (including after `destroyRouter()`).
+ *
+ * @internal Not part of the public API. Exists so asynchronous work that can
+ * acquire DOM ownership — notably `hydrateRouter()`'s bootstrap — can prove it
+ * has not been superseded. Capture before the async gap, re-check immediately
+ * before committing. A URL comparison cannot serve this purpose: an A→B→A
+ * navigation returns to the same URL under a *newer* generation, and stale work
+ * must stay superseded.
+ */
+declare function __getNavigationEpoch(): number;
+/**
+ * Whether a named route is registered.
+ *
+ * @param name The route's `name`.
+ * @returns `true` when a route with that name exists; `false` when it does not,
+ * and also when no router has been created yet.
+ */
+declare function hasRoute(name: string): boolean;
+/**
+ * Gets route information by name
+ */
+declare function getRouteInfo(name: string): RouteDef | null;
+/**
+ * Builds a URL for a route
+ */
+declare function buildURL(to: NavigationTarget): string;
+declare function destroyRouter(): void;
+/**
+ * Remove the module-level `pagehide` listener. Intended for HMR and tests —
+ * normal apps never need to call this (the listener is page-lifetime).
+ *
+ * @internal
+ */
+declare function __removeRouterPagehideHandler(): void;
+/**
+ * Outlet renders the child route component within a layout.
+ * Use inside a parent route's component to render matched children.
+ *
+ * The child is remounted when the matched child record changes or when its
+ * instance key does — by default the params declared below the top-level
+ * record, so a child-only param change remounts the child and leaves the
+ * layout in place (see `RouteBase.key`).
+ */
+declare function Outlet(): Node;
+/**
+ * Add a route at runtime.
+ */
+declare function addRoute(route: RouteDef, parentPath?: string): void;
+/**
+ * Remove a route at runtime.
+ */
+declare function removeRoute(path: string): void;
+/**
+ * routerState provides centralized reactive access to router state.
+ */
+declare function routerState(): {
+    currentPath: () => string;
+    params: () => Params;
+    query: () => Params;
+    queryAll: () => QueryValues;
+    hash: () => string;
+    meta: () => RouteMeta;
+    isNavigating: () => boolean;
+    isReady: () => boolean;
+};
+interface RouterPlugin {
+    name: string;
+    onNavigate?: (to: RouteContext, from: RouteContext) => void;
+    onError?: (error: Error, to: RouteContext) => void;
+    onReady?: () => void;
+}
+/**
+ * Register a router plugin (analytics, breadcrumbs, permissions, etc.).
+ */
+declare function routerPlugin(plugin: RouterPlugin): () => void;
+interface RouteTransitionOptions {
+    enterClass?: string;
+    leaveClass?: string;
+    duration?: number;
+}
+/**
+ * Configure route transition animations.
+ */
+declare function setRouteTransition(options: RouteTransitionOptions): void;
+/**
+ * Get current route transition options.
+ */
+declare function getRouteTransition(): RouteTransitionOptions | null;
+/**
+ * createMemoryRouter creates a router that doesn't interact with browser history.
+ * Useful for testing and SSR.
+ */
+declare function createMemoryRouter(routes: RouteDef[], _initialPath?: string): {
+    router: SibuRouter;
+    currentPath: () => string;
+    push: (path: string) => Promise<NavigationResult>;
+};
+
+/**
+ * One head value: a string, nothing, or a getter evaluated reactively against
+ * the committed route — so route params (`(r) => \`Order ${r.params.id}\``) and
+ * translated strings (`() => t("pricing.title")`) both work and stay current.
+ * `null` explicitly clears a value a parent route or the defaults set.
+ */
+type RouteHeadValue = string | null | undefined | ((route: RouteContext) => string | null | undefined);
+/** Open Graph tags a route can set. */
+interface RouteHeadOpenGraph {
+    /** `og:title`. Defaults to the route's title (without `titleTemplate`). */
+    title?: RouteHeadValue;
+    /** `og:description`. Defaults to the route's description. */
+    description?: RouteHeadValue;
+    /** `og:image` — use an ABSOLUTE URL; link-preview bots do not resolve relative ones. */
+    image?: RouteHeadValue;
+    /** `og:url`. Defaults to the canonical URL. */
+    url?: RouteHeadValue;
+    /** `og:type`, e.g. `"website"` or `"article"`. */
+    type?: RouteHeadValue;
+    /** `og:site_name`. */
+    siteName?: RouteHeadValue;
+}
+/** Twitter card tags a route can set (`twitter:*`). Declaring any turns on the fallbacks below. */
+interface RouteHeadTwitter {
+    /** `twitter:card`, e.g. `"summary_large_image"`. */
+    card?: RouteHeadValue;
+    /** `twitter:site`, the site's handle. */
+    site?: RouteHeadValue;
+    /** `twitter:creator`. */
+    creator?: RouteHeadValue;
+    /** `twitter:title`. Defaults to the Open Graph title. */
+    title?: RouteHeadValue;
+    /** `twitter:description`. Defaults to the Open Graph description. */
+    description?: RouteHeadValue;
+    /** `twitter:image` (absolute URL). Defaults to `og:image`. */
+    image?: RouteHeadValue;
+}
+/** One `<link rel="alternate" hreflang>` translation of the page. */
+interface RouteHeadAlternate {
+    /** BCP 47 language tag, or `"x-default"`. */
+    hreflang: string;
+    /** Absolute URL of the translated page. */
+    href: RouteHeadValue;
+}
+/**
+ * A JSON-LD object (`{ "@context": "https://schema.org", "@type": "Product", … }`).
+ * Serialized with `JSON.stringify` and the script escaping `serializeState`
+ * uses, so `</script>`, `<!--` and U+2028/U+2029 in the data cannot leave the
+ * script element.
+ */
+type JsonLd = {
+    [key: string]: JsonLdValue;
+};
+type JsonLdValue = string | number | boolean | null | JsonLdValue[] | {
+    [key: string]: JsonLdValue;
+};
+/**
+ * The `head` of a route record (and of `createRouter({ head })`, as defaults).
+ *
+ * Nested records merge field by field, the deepest record winning; the router
+ * defaults sit underneath every route.
+ */
+interface RouteHead {
+    /** `document.title`. */
+    title?: RouteHeadValue;
+    /** `<meta name="description">`. */
+    description?: RouteHeadValue;
+    /** `<link rel="canonical">` — use an absolute URL. */
+    canonical?: RouteHeadValue;
+    /** Open Graph tags. */
+    og?: RouteHeadOpenGraph;
+    /**
+     * Any other `<meta>` entries (`{ name: "robots", content: "noindex" }`,
+     * `{ name: "twitter:card", content: "summary_large_image" }`). Identified by
+     * their `name` or `property`; an entry with neither is ignored.
+     */
+    meta?: Record<string, RouteHeadValue>[];
+    /** `<meta name="robots">`, e.g. `"noindex, nofollow"`. A `noindex` route is left out of the sitemap. */
+    robots?: RouteHeadValue;
+    /** Twitter card tags. */
+    twitter?: RouteHeadTwitter;
+    /** Translations of the page (`<link rel="alternate" hreflang>`), identified by `hreflang`. */
+    alternates?: RouteHeadAlternate[] | ((route: RouteContext) => RouteHeadAlternate[]);
+    /** Structured data: one or more JSON-LD objects, or a getter returning them. */
+    jsonLd?: JsonLd | JsonLd[] | ((route: RouteContext) => JsonLd | JsonLd[] | null | undefined);
+}
+/** Router-level head options: defaults for every route, plus the title template. */
+interface RouterHeadOptions extends RouteHead {
+    /**
+     * Wraps every route title: `"%s · Studio"` or `(title) => \`${title} · Studio\``.
+     * Not applied to the default title itself.
+     */
+    titleTemplate?: string | ((title: string) => string);
+}
+/** One resolved `<head>` element, keyed by what it describes. */
+interface ResolvedHeadTag {
+    /** Identity used to replace / remove the tag across navigations. */
+    key: string;
+    tag: "meta" | "link" | "script";
+    attrs: Record<string, string>;
+    /** Text content (the escaped JSON of a JSON-LD script). */
+    text?: string;
+}
+/** The head a route resolves to. */
+interface ResolvedRouteHead {
+    title: string | null;
+    tags: ResolvedHeadTag[];
+}
+/**
+ * Serialize JSON-LD for a `<script type="application/ld+json">` body: `<`, `>`,
+ * `&`, U+2028 and U+2029 become `\u` escapes, which JSON parsers read back as
+ * the original characters, so the data can never close the script element.
+ *
+ * @param data One JSON-LD object or a list of them.
+ * @returns The escaped JSON text.
+ */
+declare function serializeJsonLd(data: JsonLd | JsonLd[]): string;
+/**
+ * A complete JSON-LD `<script>` element, for a backend template or a static
+ * page. The only non-executable script SibuJS emits: its type is
+ * `application/ld+json` and its body is {@link serializeJsonLd}'s output.
+ *
+ * @param data One JSON-LD object or a list of them.
+ * @returns `<script type="application/ld+json">…</script>`.
+ */
+declare function jsonLdScript(data: JsonLd | JsonLd[]): string;
+/**
+ * Resolve the head a committed route renders: the router defaults, then every
+ * matched record from the root down. Getters are invoked here, so calling this
+ * inside an effect subscribes to whatever they read.
+ *
+ * @param route The committed route.
+ * @param defaults `createRouter({ head })`, if any.
+ * @returns The title and the tags, after the shared head policy.
+ */
+declare function resolveRouteHead(route: RouteContext, defaults?: RouterHeadOptions): ResolvedRouteHead;
+/**
+ * Serialize a resolved head to HTML, for SSR or a static page. Each tag carries
+ * the `data-sibu-head` marker so the client router adopts it on start-up
+ * instead of duplicating it.
+ *
+ * @param head The result of {@link resolveRouteHead}.
+ * @returns `<title>` plus one element per tag.
+ */
+declare function routeHeadToHTML(head: ResolvedRouteHead): string;
+
+export { forward as $, type AsyncComponent as A, type RouterPlugin as B, type Component as C, type ScrollPosition as D, SibuRouter as E, Suspense as F, type Guard as G, __removeRouterPagehideHandler as H, addRoute as I, type JsonLd as J, KeepAliveRoute as K, type LazyComponent as L, afterEach as M, type NavigationFailure as N, Outlet as O, type Params as P, type QueryValues as Q, type RouterOptions as R, type ScrollBehavior as S, back as T, beforeEach as U, beforeResolve as V, buildURL as W, createMemoryRouter as X, createRouter as Y, destroyRouter as Z, __getNavigationEpoch as _, type RouteDef as a, getRouteInfo as a0, getRouteTransition as a1, go as a2, hasRoute as a3, jsonLdScript as a4, lazy as a5, navigate as a6, preloadRoute as a7, push as a8, removeRoute as a9, replace as aa, resolveRouteHead as ab, route as ac, routeHeadToHTML as ad, router as ae, routerPlugin as af, routerReady as ag, routerState as ah, serializeJsonLd as ai, setRouteTransition as aj, setRoutes as ak, type AsyncRoute as b, type ComponentRoute as c, type GuardResult as d, type LazyRoute as e, type NavigationFailureReason as f, type NavigationGuard as g, type NavigationNext as h, type NavigationQuery as i, type NavigationResult as j, type NavigationTarget as k, type RedirectRoute as l, type ResolvedHeadTag as m, type ResolvedRouteHead as n, Route as o, type RouteBase as p, type RouteContext as q, type RouteHead as r, type RouteHeadAlternate as s, type RouteHeadOpenGraph as t, type RouteHeadTwitter as u, type RouteHeadValue as v, type RouteMeta as w, type RouteTransitionOptions as x, type RouterHeadOptions as y, RouterLink as z };