sibujs 3.4.0 → 4.0.0

package/dist/plugins.d.cts

@@ -1,19 +1,73 @@
-import { T as TrustedHTML } from './ssr-D62yFwuw.cjs';
+import { T as TrustedHTML } from './ssr-BiPRdZ6n.cjs';
 export { P as PluginContext, a as PluginRegistry, S as SibuPlugin, c as createPlugin, b as createPluginRegistry, i as inject, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, d as triggerPluginMount, e as triggerPluginUnmount } from './plugin-D30wlGW5.cjs';
-export { M as Migration, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, a as compareSemVer, d as createBootSequence, e as createBundle, f as createMigrationRunner, g as createModuleRegistry, h as createSSRCache, i as createTestHarness, j as deferNonCritical, k as env, l as healthCheck, m as lazyModule, p as packageInfo, n as parseSemVer, o as preloadCritical, q as prerenderRoutes, s as satisfies } from './startup-0Qv6aosO.cjs';
+export { M as Migration, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, a as compareSemVer, d as createBootSequence, e as createBundle, f as createMigrationRunner, g as createModuleRegistry, h as createSSRCache, i as createTestHarness, j as deferNonCritical, k as env, l as healthCheck, m as lazyModule, p as packageInfo, n as parseSemVer, o as preloadCritical, q as prerenderRoutes, s as satisfies } from './startup-BMpaiMhP.cjs';
 
 type Translations = Record<string, string>;
 type Params$1 = Record<string, string | number>;
+/**
+ * Set the active locale.
+ *
+ * Inside an SSR request this sets the locale for THAT request only, leaving the
+ * application-wide default alone, so one request can never change what a
+ * concurrent one renders. Outside a request it updates the client locale
+ * reactively, exactly as before.
+ */
 declare function setLocale(locale: string): void;
 /**
- * Get the current locale reactively.
+ * Get the current locale.
+ *
+ * Inside an SSR request this is the locale that request selected, or — when it
+ * never called `setLocale()` — the application default, which preserves the
+ * established `"en"` behaviour while still honouring an application that sets a
+ * different default at startup.
+ *
+ * Outside a request it is the client locale, and the read is reactive: a
+ * subscriber re-runs when `setLocale()` changes it.
  */
 declare function getLocale(): string;
+/**
+ * Register translation messages for a locale.
+ *
+ * Dictionaries are APPLICATION-GLOBAL, including when this is called from
+ * inside an SSR request: messages registered anywhere are visible everywhere,
+ * and merging preserves whatever was registered before.
+ *
+ * PREPARE, THEN COMMIT. `messages` is caller-controlled, and spreading it runs
+ * the caller's property getters and proxy traps — arbitrary synchronous code
+ * that can call this function again. Merging in a single expression
+ *
+ *     locales[locale] = { ...locales[locale], ...messages };
+ *
+ * captures the dictionary BEFORE that code runs and writes it back after, so a
+ * nested registration that committed in between is silently erased. Copying
+ * `messages` first leaves a plain object with no getters left, so by the time
+ * the live dictionary is read for the merge no caller code can run again.
+ *
+ * Precedence, deliberately: the outer call's prepared values win over a nested
+ * call's for the same key — it is the registration the caller asked for last,
+ * and its value was computed from what it intended to publish. Nested keys the
+ * outer object does not mention survive untouched.
+ *
+ * A getter that throws leaves the dictionary exactly as it was: preparation has
+ * published nothing. A nested registration that completed before the throw is
+ * unaffected, because it committed on its own.
+ *
+ * Publication uses `Object.defineProperty` rather than `locales[locale] = ...`,
+ * because the assignment form would invoke the inherited `__proto__` setter for
+ * a locale of that name instead of registering it. Locale names and translation
+ * keys are treated literally throughout — see PROTOTYPE SAFETY above.
+ */
 declare function registerTranslations(locale: string, messages: Translations): void;
+/**
+ * Translate `key` in the current locale, falling back to the key itself when it
+ * is not registered. A registered empty string is a translation and is returned
+ * unchanged; the previous `|| key` discarded it and returned the key.
+ */
 declare function t(key: string, params?: Params$1): string;
 /**
  * Trans component — renders a translated string reactively.
- * Automatically updates when the locale changes.
+ * Automatically updates when the client locale changes. During SSR it renders
+ * once, using the locale belonging to the current request.
  *
  * @param key Translation key
  * @param params Optional interpolation parameters
@@ -30,11 +84,20 @@ declare function t(key: string, params?: Params$1): string;
  */
 declare function Trans(key: string, params?: Params$1): HTMLElement;
 /**
- * Check if a translation key exists for the current locale.
+ * Check if a translation key exists for the current locale — the request's
+ * locale during SSR, the client locale otherwise.
+ *
+ * Registered keys only. `toString`, `constructor` and the rest of
+ * `Object.prototype` are not translations unless an application registers them,
+ * and a registered empty string counts as present.
  */
 declare function hasTranslation(key: string): boolean;
 /**
- * Get all available locales.
+ * Get all available locales. Dictionaries are application-global, so this is
+ * the same set inside and outside a request.
+ *
+ * Own enumerable keys, so a locale is listed exactly when it was registered -
+ * including one named `"__proto__"`, which publication now stores literally.
  */
 declare function getAvailableLocales(): string[];
 
@@ -93,6 +156,20 @@ interface RouterOptions {
     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;
@@ -111,8 +188,34 @@ 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;
@@ -123,6 +226,8 @@ type NavigationResult = {
 } | {
     success: false;
     type: NavigationFailure["type"];
+    /** Mirrors `failure.reason`; see {@link NavigationFailureReason}. */
+    reason?: NavigationFailureReason;
     failure: NavigationFailure;
 };
 type NavigationTarget = string | {
@@ -132,6 +237,30 @@ type NavigationTarget = string | {
     query?: Params;
     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;
@@ -143,6 +272,8 @@ declare class SibuRouter {
     private isReadyGetter;
     private isReadySetter;
     private cleanup;
+    private destroyed;
+    private navEpoch;
     constructor(routes: RouteDef[], options?: RouterOptions);
     private initialize;
     private createInitialRoute;
@@ -153,14 +284,42 @@ declare class SibuRouter {
         replace?: boolean;
         state?: unknown;
         skipHistory?: boolean;
+        initialResolution?: boolean;
     }): Promise<NavigationResult>;
     private static readonly MAX_REDIRECT_DEPTH;
     private performNavigation;
     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;
-    loadComponent(route: RouteDef, routePath: string): Promise<Component>;
+    /**
+     * 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. */
+    instantiateComponent(plan: RoutePlan, route: RouteDef, routePath: string): 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;
@@ -171,6 +330,8 @@ declare class SibuRouter {
     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;
@@ -229,6 +390,30 @@ declare function Route(): Node;
  * 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
@@ -259,7 +444,28 @@ declare function RouterLink(props: {
     target?: string;
     rel?: string;
     [key: string]: unknown;
-}, children?: string | Node | (string | Node)[]): HTMLElement;
+}, children?: string | Node | (string | Node)[]): 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: {
     fallback?: () => HTMLElement | HTMLElement;
     nodes: () => HTMLElement | Promise<HTMLElement>;
@@ -279,6 +485,18 @@ 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;
 declare function hasRoute(name: string): boolean;
 /**
  * Gets route information by name
@@ -464,4 +682,4 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
     }) => string;
 };
 
-export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };
+export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };