@fluixi/core 1.0.0-alpha.84 → 1.0.0-alpha.85

package/dist/src/lib/router/transition.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Navigation presentation: preparing a route before it is shown, and handing the DOM
+ * swap to the browser's View Transition API when there is one.
+ *
+ * ## The lifecycle this replaces
+ *
+ * Navigation used to be one synchronous chain. `navigate()` pushed history, the core
+ * router recomputed the match and notified, the `Router` component wrote the match
+ * signal, and the render memo rebuilt the layer at the depth that changed. The old DOM
+ * came out at that moment: whether or not the new route had anything to put in its
+ * place:
+ *
+ *   - a route with a `data` loader renders `null` until the resource resolves,
+ *   - a `lazy()` route whose chunk is not loaded suspends to the nearest fallback.
+ *
+ * Both are an empty intermediate state with the old page already gone, which is what
+ * reads as a flash. It is not a paint-timing artifact and no animation would hide it.
+ *
+ * ## The lifecycle now
+ *
+ *   navigation-start
+ *        │  the match is computed, but not committed
+ *   prepare
+ *        │  every matched layer's module is loaded (`lazy().preload()`), so the
+ *        │  component renders synchronously instead of suspending
+ *   begin transition
+ *        │  `document.startViewTransition`, when it applies
+ *   commit
+ *        │  the match signal is written and effects are flushed, inside the
+ *        │  transition's callback, so the browser snapshots a settled DOM
+ *   navigation-complete
+ *
+ * Nothing here delays anything. The commit happens as soon as preparation resolves; on
+ * a warm route that is the same tick it always was.
+ */
+/** How a navigation should be presented. */
+export type TransitionMode = 'auto' | 'none';
+/**
+ * Whether this environment can animate a route swap.
+ *
+ * Read at call time rather than cached at module load: a test swaps the API in and out,
+ * and a cached answer would make the second case unreachable.
+ */
+export declare function supportsViewTransitions(): boolean;
+/**
+ * Whether the reader asked not to be animated.
+ *
+ * A stated preference outranks the app's configuration, so this is checked on every
+ * navigation rather than once: the setting can change while the page is open.
+ */
+export declare function prefersReducedMotion(): boolean;
+/** Whether this particular commit should go through a view transition. */
+export declare function shouldAnimate(mode: TransitionMode): boolean;
+/**
+ * Load what the next route needs to render without suspending.
+ *
+ * Only the route's own modules. Data loaders are deliberately left alone: the resource
+ * belongs to the layer's owner and is created when that layer renders, so calling the
+ * loader here would either run the request twice or require a cache this router does not
+ * own. See the note in the router on what that leaves.
+ *
+ * A module that fails to load resolves anyway. Preparation is an optimisation, and a
+ * rejected import should surface through the route's own error handling when it renders,
+ * not by leaving the navigation permanently pending.
+ */
+export declare function prepareComponents(components: readonly unknown[]): Promise<void> | null;
+/**
+ * Run `commit` inside a view transition, or directly when one does not apply.
+ *
+ * The callback is async because writing the match signal only queues the work: effects
+ * are scheduled, so the DOM is not settled when the write returns. `startViewTransition`
+ * waits for the returned promise before snapshotting the new state, so flushing inside
+ * it is what makes the browser compare two finished frames rather than one finished and
+ * one half-built.
+ *
+ * The returned promise resolves when the DOM has been updated, not when the animation
+ * ends. A caller waiting on navigation wants the former; blocking on the latter would
+ * make every navigation as slow as its animation.
+ */
+export declare function runTransition(mode: TransitionMode, commit: () => void | Promise<void>): Promise<void>;
+//# sourceMappingURL=transition.d.ts.map

package/dist/src/lib/router/transition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.d.ts","sourceRoot":"","sources":["../../../../src/lib/router/transition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAcH,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAU9C;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAqBtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/src/lib/router/transition.js

@@ -0,0 +1,136 @@
+/**
+ * Navigation presentation: preparing a route before it is shown, and handing the DOM
+ * swap to the browser's View Transition API when there is one.
+ *
+ * ## The lifecycle this replaces
+ *
+ * Navigation used to be one synchronous chain. `navigate()` pushed history, the core
+ * router recomputed the match and notified, the `Router` component wrote the match
+ * signal, and the render memo rebuilt the layer at the depth that changed. The old DOM
+ * came out at that moment: whether or not the new route had anything to put in its
+ * place:
+ *
+ *   - a route with a `data` loader renders `null` until the resource resolves,
+ *   - a `lazy()` route whose chunk is not loaded suspends to the nearest fallback.
+ *
+ * Both are an empty intermediate state with the old page already gone, which is what
+ * reads as a flash. It is not a paint-timing artifact and no animation would hide it.
+ *
+ * ## The lifecycle now
+ *
+ *   navigation-start
+ *        │  the match is computed, but not committed
+ *   prepare
+ *        │  every matched layer's module is loaded (`lazy().preload()`), so the
+ *        │  component renders synchronously instead of suspending
+ *   begin transition
+ *        │  `document.startViewTransition`, when it applies
+ *   commit
+ *        │  the match signal is written and effects are flushed, inside the
+ *        │  transition's callback, so the browser snapshots a settled DOM
+ *   navigation-complete
+ *
+ * Nothing here delays anything. The commit happens as soon as preparation resolves; on
+ * a warm route that is the same tick it always was.
+ */
+/**
+ * Whether this environment can animate a route swap.
+ *
+ * Read at call time rather than cached at module load: a test swaps the API in and out,
+ * and a cached answer would make the second case unreachable.
+ */
+export function supportsViewTransitions() {
+    return (typeof document !== 'undefined' &&
+        typeof document
+            .startViewTransition === 'function');
+}
+/**
+ * Whether the reader asked not to be animated.
+ *
+ * A stated preference outranks the app's configuration, so this is checked on every
+ * navigation rather than once: the setting can change while the page is open.
+ */
+export function prefersReducedMotion() {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+        return false;
+    }
+    try {
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    catch {
+        // A matchMedia that throws on an unknown query is not a reason to fail navigation.
+        return false;
+    }
+}
+/** Whether this particular commit should go through a view transition. */
+export function shouldAnimate(mode) {
+    return mode !== 'none' && supportsViewTransitions() && !prefersReducedMotion();
+}
+/**
+ * Load what the next route needs to render without suspending.
+ *
+ * Only the route's own modules. Data loaders are deliberately left alone: the resource
+ * belongs to the layer's owner and is created when that layer renders, so calling the
+ * loader here would either run the request twice or require a cache this router does not
+ * own. See the note in the router on what that leaves.
+ *
+ * A module that fails to load resolves anyway. Preparation is an optimisation, and a
+ * rejected import should surface through the route's own error handling when it renders,
+ * not by leaving the navigation permanently pending.
+ */
+export function prepareComponents(components) {
+    const pending = [];
+    for (const component of components) {
+        const preload = component
+            ?.preload;
+        if (typeof preload === 'function') {
+            try {
+                const result = preload();
+                if (result && typeof result.then === 'function') {
+                    pending.push(result.catch(() => undefined));
+                }
+            }
+            catch {
+                // A preload that throws synchronously is the same as one that rejects.
+            }
+        }
+    }
+    // Null rather than a resolved promise: the caller commits synchronously when there is
+    // nothing to wait for, which keeps a warm navigation on the tick it was already on.
+    return pending.length ? Promise.all(pending).then(() => undefined) : null;
+}
+/**
+ * Run `commit` inside a view transition, or directly when one does not apply.
+ *
+ * The callback is async because writing the match signal only queues the work: effects
+ * are scheduled, so the DOM is not settled when the write returns. `startViewTransition`
+ * waits for the returned promise before snapshotting the new state, so flushing inside
+ * it is what makes the browser compare two finished frames rather than one finished and
+ * one half-built.
+ *
+ * The returned promise resolves when the DOM has been updated, not when the animation
+ * ends. A caller waiting on navigation wants the former; blocking on the latter would
+ * make every navigation as slow as its animation.
+ */
+export function runTransition(mode, commit) {
+    if (!shouldAnimate(mode)) {
+        return Promise.resolve(commit()).then(() => undefined);
+    }
+    const start = document
+        .startViewTransition;
+    try {
+        const transition = start.call(document, () => commit());
+        // Swallow the rejections a skipped or interrupted transition produces. Both of
+        // these reject when the animation is cut short, by `skipTransition()`, by another
+        // navigation starting, or by the tab going to the background. The DOM update inside
+        // the callback still happened, so a navigation must not fail because an animation
+        // did not play, and an unobserved rejection here would surface as an unhandled one.
+        transition.finished?.catch(() => undefined);
+        transition.ready?.catch(() => undefined);
+        return transition.updateCallbackDone.catch(() => undefined);
+    }
+    catch {
+        // A browser that has the method but refuses the call still has to navigate.
+        return Promise.resolve(commit()).then(() => undefined);
+    }
+}

package/dist/src/lib/router/transition.mjs

@@ -0,0 +1,54 @@
+// src/lib/router/transition.ts
+function supportsViewTransitions() {
+  return typeof document !== "undefined" && typeof document.startViewTransition === "function";
+}
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  try {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  } catch {
+    return false;
+  }
+}
+function shouldAnimate(mode) {
+  return mode !== "none" && supportsViewTransitions() && !prefersReducedMotion();
+}
+function prepareComponents(components) {
+  const pending = [];
+  for (const component of components) {
+    const preload = component?.preload;
+    if (typeof preload === "function") {
+      try {
+        const result = preload();
+        if (result && typeof result.then === "function") {
+          pending.push(result.catch(() => void 0));
+        }
+      } catch {
+      }
+    }
+  }
+  return pending.length ? Promise.all(pending).then(() => void 0) : null;
+}
+function runTransition(mode, commit) {
+  if (!shouldAnimate(mode)) {
+    return Promise.resolve(commit()).then(() => void 0);
+  }
+  const start = document.startViewTransition;
+  try {
+    const transition = start.call(document, () => commit());
+    transition.finished?.catch(() => void 0);
+    transition.ready?.catch(() => void 0);
+    return transition.updateCallbackDone.catch(() => void 0);
+  } catch {
+    return Promise.resolve(commit()).then(() => void 0);
+  }
+}
+export {
+  prefersReducedMotion,
+  prepareComponents,
+  runTransition,
+  shouldAnimate,
+  supportsViewTransitions
+};

package/dist/src/lib/server/index.cjs

@@ -1,4 +1,4 @@
-/*! @fluixi/core v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/core v1.0.0-alpha.85 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/src/lib/server/index.mjs

@@ -1,4 +1,4 @@
-/*! @fluixi/core v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/core v1.0.0-alpha.85 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 
 // src/lib/server/hydration.ts
 import { isServer as domIsServer } from "@fluixi/dom";

package/dist/src/routes.cjs

@@ -1,4 +1,4 @@
-/*! @fluixi/core v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/core v1.0.0-alpha.85 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/src/routes.mjs

@@ -1,4 +1,4 @@
-/*! @fluixi/core v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/core v1.0.0-alpha.85 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 
 // src/routes.ts
 function missingPlugin() {

package/dist/src/utils.cjs

@@ -1,4 +1,4 @@
-/*! @fluixi/core v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/core v1.0.0-alpha.85 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/src/utils.mjs

@@ -1,4 +1,4 @@
-/*! @fluixi/core v1.0.0-alpha.84 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+/*! @fluixi/core v1.0.0-alpha.85 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
 
 // src/utils.ts
 export * from "@fluixi/utils";

package/dist/src/version.generated.cjs

@@ -23,4 +23,4 @@ __export(version_generated_exports, {
   VERSION: () => VERSION
 });
 module.exports = __toCommonJS(version_generated_exports);
-var VERSION = "1.0.0-alpha.84";
+var VERSION = "1.0.0-alpha.85";

package/dist/src/version.generated.d.ts

@@ -1,3 +1,3 @@
 /** The published version of @fluixi/core that this build came from. */
-export declare const VERSION = "1.0.0-alpha.84";
+export declare const VERSION = "1.0.0-alpha.85";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/src/version.generated.js

@@ -1,3 +1,3 @@
 // GENERATED by scripts/gen-version.mjs. Do not edit.
 /** The published version of @fluixi/core that this build came from. */
-export const VERSION = '1.0.0-alpha.84';
+export const VERSION = '1.0.0-alpha.85';

package/dist/src/version.generated.mjs

@@ -1,5 +1,5 @@
 // src/version.generated.ts
-var VERSION = "1.0.0-alpha.84";
+var VERSION = "1.0.0-alpha.85";
 export {
   VERSION
 };