alepha 0.22.0 → 0.24.0

package/src/react/router/__tests__/$page.spec.tsx

@@ -1,4 +1,4 @@
-import { Alepha, OPTIONS, t } from "alepha";
+import { Alepha, OPTIONS, z } from "alepha";
 import { $cache } from "alepha/cache";
 import type { FC } from "react";
 import { beforeEach, describe, test, vi } from "vitest";
@@ -60,12 +60,12 @@ describe("$page primitive tests", () => {
       user = $page({
         path: "/user/:id",
         schema: {
-          params: t.object({
-            id: t.text(),
+          params: z.object({
+            id: z.text(),
           }),
-          query: t.object({
-            tab: t.text({ default: "profile" }),
-            sort: t.optional(t.text()),
+          query: z.object({
+            tab: z.text({ default: "profile" }),
+            sort: z.text().optional(),
           }),
         },
         loader: ({ params, query }) => ({ params, query }),
@@ -144,8 +144,8 @@ describe("$page primitive tests", () => {
       async = $page({
         path: "/async/:id",
         schema: {
-          params: t.object({
-            id: t.text(),
+          params: z.object({
+            id: z.text(),
           }),
         },
         loader: async ({ params }) => {
@@ -343,8 +343,8 @@ describe("$page primitive tests", () => {
       staticWithEntries = $page({
         path: "/static/:id",
         schema: {
-          params: t.object({
-            id: t.text(),
+          params: z.object({
+            id: z.text(),
           }),
         },
         static: {
@@ -515,18 +515,18 @@ describe("$page primitive tests", () => {
       complex = $page({
         path: "/complex/:userId",
         schema: {
-          params: t.object({
-            userId: t.text(),
+          params: z.object({
+            userId: z.text(),
           }),
-          query: t.object({
-            filters: t.optional(
-              t.object({
-                status: t.text({ default: "active" }),
-                category: t.optional(t.text()),
-              }),
-            ),
-            page: t.number({ default: 1 }),
-            limit: t.number({ default: 10 }),
+          query: z.object({
+            filters: z
+              .object({
+                status: z.text({ default: "active" }),
+                category: z.text().optional(),
+              })
+              .optional(),
+            page: z.number().default(1),
+            limit: z.number().default(10),
           }),
         },
         loader: ({ params, query }) => ({

package/src/react/router/__tests__/ReactBrowserProvider.browser.spec.ts

@@ -1,7 +1,8 @@
-import { Alepha } from "alepha";
+import { $atom, Alepha, z } from "alepha";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   ReactBrowserProvider,
+  type ReactHydrationState,
   type RouterPushOptions,
   reactBrowserOptions,
 } from "../providers/ReactBrowserProvider.ts";
@@ -9,6 +10,7 @@ import {
 class TestReactBrowserProvider extends ReactBrowserProvider {
   public testGetHydrationState = this.getHydrationState.bind(this);
   public testAttachAnchorInterceptor = this.attachAnchorInterceptor.bind(this);
+  public testApplyHydration = this.applyHydration.bind(this);
   public pushCalls: Array<{ url: string; options?: RouterPushOptions }> = [];
 
   public override async push(
@@ -116,6 +118,65 @@ describe("ReactBrowserProvider", () => {
     });
   });
 
+  describe("applyHydration", () => {
+    const testAtom = $atom({
+      name: "test.hydration.settings",
+      schema: z.object({ theme: z.string() }),
+      default: { theme: "light" },
+    });
+
+    it("writes a valid hydrated value through, parsed against the schema", () => {
+      alepha.store.get(testAtom); // pre-register, as a real app would
+
+      provider.testApplyHydration({
+        [testAtom.key]: { theme: "dark", junk: true },
+      } as unknown as ReactHydrationState);
+
+      expect(alepha.store.get(testAtom)).toEqual({ theme: "dark" });
+    });
+
+    it("keeps the default and warns when a hydrated value fails schema validation", async () => {
+      alepha.store.get(testAtom); // pre-register, as a real app would
+
+      const onLog = vi.fn();
+      alepha.events.on("log", onLog);
+
+      provider.testApplyHydration({
+        [testAtom.key]: { theme: 42 },
+      } as unknown as ReactHydrationState);
+
+      // Logger delivery is event-based and async — flush before asserting.
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(alepha.store.get(testAtom)).toEqual({ theme: "light" });
+      expect(
+        onLog.mock.calls.some(([payload]) =>
+          payload.entry?.message?.includes(testAtom.key),
+        ),
+      ).toBe(true);
+    });
+
+    it("passes through a not-yet-registered atom value, decoded later at registration", () => {
+      provider.testApplyHydration({
+        [testAtom.key]: { theme: "dark", junk: true },
+      } as unknown as ReactHydrationState);
+
+      // First access registers the atom and decodes the raw hydrated value
+      // (StateManager.register()'s decode-at-registration path).
+      expect(alepha.store.get(testAtom)).toEqual({ theme: "dark" });
+    });
+
+    it("skips alepha.react.router.layers — it is not treated as an atom value", () => {
+      provider.testApplyHydration({
+        "alepha.react.router.layers": [{ name: "home" }],
+      } as ReactHydrationState);
+
+      expect(
+        alepha.store.getAtom("alepha.react.router.layers"),
+      ).toBeUndefined();
+    });
+  });
+
   describe("attachAnchorInterceptor", () => {
     let alepha: Alepha;
     let provider: TestReactBrowserProvider;
@@ -313,4 +374,29 @@ describe("ReactBrowserProvider", () => {
       expect(provider.pushCalls).toHaveLength(0);
     });
   });
+
+  /**
+   * `url` is what `push()` compares the committed route against and what gets
+   * written back to history. Dropping the fragment here made every internal
+   * `<a href="/docs#section">` land on /docs with no anchor, never scrolling.
+   */
+  describe("url", () => {
+    it("keeps the hash fragment", () => {
+      window.history.pushState({}, "", "/docs#section");
+
+      expect(provider.url).toBe("/docs#section");
+    });
+
+    it("keeps the hash alongside the query string", () => {
+      window.history.pushState({}, "", "/docs?q=1#section");
+
+      expect(provider.url).toBe("/docs?q=1#section");
+    });
+
+    it("is unchanged when there is no hash", () => {
+      window.history.pushState({}, "", "/docs?q=1");
+
+      expect(provider.url).toBe("/docs?q=1");
+    });
+  });
 });

package/src/react/router/__tests__/RouterLocaleProvider.spec.ts

@@ -0,0 +1,127 @@
+import { Alepha } from "alepha";
+import { describe, test } from "vitest";
+import { RouterLocaleProvider } from "../providers/RouterLocaleProvider.ts";
+
+describe("RouterLocaleProvider", () => {
+  const setup = (config?: Parameters<RouterLocaleProvider["configure"]>[0]) => {
+    const alepha = Alepha.create();
+    const provider = alepha.inject(RouterLocaleProvider);
+    if (config) {
+      provider.configure(config);
+    }
+    return provider;
+  };
+
+  describe("when disabled (default)", () => {
+    test("detect leaves the pathname untouched", ({ expect }) => {
+      const provider = setup();
+      expect(provider.detect("/fr/about")).toEqual({
+        locale: "",
+        pathname: "/fr/about",
+      });
+    });
+
+    test("withPrefix returns the pathname unchanged", ({ expect }) => {
+      const provider = setup();
+      expect(provider.withPrefix("/about", "fr")).toBe("/about");
+    });
+  });
+
+  describe("when enabled with default 'en' and locales [en, fr, de]", () => {
+    const config = {
+      enabled: true,
+      defaultLocale: "en",
+      locales: ["en", "fr", "de"],
+    };
+
+    test("exposes only non-default locales as prefixed", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.prefixedLocales).toEqual(["fr", "de"]);
+    });
+
+    test("detect strips a known prefixed locale", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.detect("/fr/about")).toEqual({
+        locale: "fr",
+        pathname: "/about",
+      });
+    });
+
+    test("detect treats an unprefixed path as the default locale", ({
+      expect,
+    }) => {
+      const provider = setup(config);
+      expect(provider.detect("/about")).toEqual({
+        locale: "en",
+        pathname: "/about",
+      });
+    });
+
+    test("detect ignores a segment that is the default locale", ({
+      expect,
+    }) => {
+      const provider = setup(config);
+      // /en is NOT a prefixed locale (default is unprefixed), so it is a normal path
+      expect(provider.detect("/en/about")).toEqual({
+        locale: "en",
+        pathname: "/en/about",
+      });
+    });
+
+    test("detect normalizes the bare locale root to '/'", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.detect("/fr")).toEqual({ locale: "fr", pathname: "/" });
+      expect(provider.detect("/fr/")).toEqual({ locale: "fr", pathname: "/" });
+    });
+
+    test("detect strips a deep prefixed path", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.detect("/de/c/42/quest")).toEqual({
+        locale: "de",
+        pathname: "/c/42/quest",
+      });
+    });
+
+    test("withPrefix prepends a non-default locale", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/about", "fr")).toBe("/fr/about");
+    });
+
+    test("withPrefix leaves the default locale unprefixed", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/about", "en")).toBe("/about");
+    });
+
+    test("withPrefix handles the root path", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/", "fr")).toBe("/fr");
+    });
+
+    test("withPrefix ignores an unknown locale", ({ expect }) => {
+      const provider = setup(config);
+      expect(provider.withPrefix("/about", "zz")).toBe("/about");
+    });
+  });
+
+  describe("current locale (store-backed)", () => {
+    test("defaults to the default locale", ({ expect }) => {
+      const provider = setup({
+        enabled: true,
+        defaultLocale: "en",
+        locales: ["en", "fr"],
+      });
+      expect(provider.current).toBe("en");
+    });
+
+    test("withPrefix uses current() when no locale is passed", ({ expect }) => {
+      const provider = setup({
+        enabled: true,
+        defaultLocale: "en",
+        locales: ["en", "fr"],
+      });
+      provider.current = "fr";
+      expect(provider.current).toBe("fr");
+      expect(provider.withPrefix("/about")).toBe("/fr/about");
+    });
+  });
+});

package/src/react/router/atoms/ssrManifestAtom.ts

@@ -1,51 +1,51 @@
-import { $atom, t } from "alepha";
+import { $atom, z } from "alepha";
 
 /**
  * Schema for the SSR manifest atom.
  */
-export const ssrManifestAtomSchema = t.object({
+export const ssrManifestAtomSchema = z.object({
   /**
    * Base path for assets (from Vite's base config).
    * Used to prefix asset URLs when serving from a subpath.
    * @example "/devtools" or "/"
    */
-  base: t.optional(t.string()),
+  base: z.string().optional(),
 
   /**
    * Preload manifest mapping short keys to source paths.
    * Generated by viteAlephaSsrPreload plugin at build time.
    */
-  preload: t.optional(t.record(t.string(), t.string())),
+  preload: z.record(z.string(), z.string()).optional(),
 
   /**
    * Client manifest mapping source files to their output information.
    * Only includes fields actually used for preloading.
    */
-  client: t.optional(
-    t.record(
-      t.string(),
-      t.object({
-        file: t.string(),
-        isEntry: t.optional(t.boolean()),
-        imports: t.optional(t.array(t.string())),
-        css: t.optional(t.array(t.string())),
+  client: z
+    .record(
+      z.string(),
+      z.object({
+        file: z.string(),
+        isEntry: z.boolean().optional(),
+        imports: z.array(z.string()).optional(),
+        css: z.array(z.string()).optional(),
       }),
-    ),
-  ),
+    )
+    .optional(),
 
   /**
    * Dev mode head content.
    * Contains pre-transformed scripts injected by Vite and plugins (React, etc.).
    * Only set in dev mode via ViteDevServerProvider.
    */
-  devHead: t.optional(t.string()),
+  devHead: z.string().optional(),
 
   /**
    * Auto-detected favicon path and MIME type.
    * Format: "type:path" (e.g., "image/svg+xml:/favicon.svg").
    * Set at build/dev time by scanning the public directory.
    */
-  favicon: t.optional(t.string()),
+  favicon: z.string().optional(),
 });
 
 /**

package/src/react/router/components/NestedView.tsx

@@ -39,7 +39,12 @@ const NestedView = (props: NestedViewProps) => {
   const onError = routerLayer?.onError;
   const state = useRouterState();
   const alepha = useAlepha();
-  const [boundaryKey, setBoundaryKey] = useState(0);
+
+  // Navigating away from a page that threw must clear the boundary — otherwise
+  // the fallback latches and every later page keeps rendering the old error
+  // until a full reload. Resetting on the path (rather than remounting via
+  // `key`) recovers without tearing down the children on every navigation.
+  const boundaryResetKeys = [state.url.pathname];
 
   const [view, setView] = useState<ReactNode | undefined>(
     state.layers[index]?.element,
@@ -148,7 +153,10 @@ const NestedView = (props: NestedViewProps) => {
 
   if (props.errorBoundary) {
     return (
-      <ErrorBoundary key={boundaryKey} fallback={props.errorBoundary}>
+      <ErrorBoundary
+        fallback={props.errorBoundary}
+        resetKeys={boundaryResetKeys}
+      >
         {element}
       </ErrorBoundary>
     );
@@ -165,7 +173,7 @@ const NestedView = (props: NestedViewProps) => {
   };
 
   return (
-    <ErrorBoundary key={boundaryKey} fallback={fallback}>
+    <ErrorBoundary fallback={fallback} resetKeys={boundaryResetKeys}>
       {element}
     </ErrorBoundary>
   );

package/src/react/router/hooks/useQueryParams.ts

@@ -18,7 +18,7 @@ import { useRouter } from "./useRouter.ts";
  *
  * @example
  * const [params, setParams] = useQueryParams(
- *   t.object({ tab: t.optional(t.string()) }),
+ *   z.object({ tab: z.string().optional() }),
  *   { format: "querystring" },
  * );
  * // params.tab reads from `?tab=…`; setParams({ tab: "security" }) writes it.

package/src/react/router/index.browser.ts

@@ -9,6 +9,7 @@ import { ReactBrowserProvider } from "./providers/ReactBrowserProvider.ts";
 import { ReactBrowserRendererProvider } from "./providers/ReactBrowserRendererProvider.ts";
 import { ReactBrowserRouterProvider } from "./providers/ReactBrowserRouterProvider.ts";
 import { ReactPageProvider } from "./providers/ReactPageProvider.ts";
+import { RouterLocaleProvider } from "./providers/RouterLocaleProvider.ts";
 import { ReactPageService } from "./services/ReactPageService.ts";
 import { ReactRouter } from "./services/ReactRouter.ts";
 
@@ -18,6 +19,7 @@ export * from "./index.shared.ts";
 export * from "./providers/ReactBrowserProvider.ts";
 export * from "./providers/ReactBrowserRendererProvider.ts";
 export * from "./providers/ReactBrowserRouterProvider.ts";
+export * from "./providers/RouterLocaleProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -30,6 +32,7 @@ export const AlephaReactRouter = $module({
     ReactBrowserProvider,
     ReactRouter,
     ReactBrowserRendererProvider,
+    RouterLocaleProvider,
     ReactPageService,
   ],
   register: (alepha) =>
@@ -43,5 +46,6 @@ export const AlephaReactRouter = $module({
       .with(ReactBrowserProvider)
       .with(ReactBrowserRouterProvider)
       .with(ReactBrowserRendererProvider)
+      .with(RouterLocaleProvider)
       .with(ReactRouter),
 });

package/src/react/router/index.shared.ts

@@ -15,5 +15,6 @@ export * from "./hooks/useRouter.ts";
 export * from "./hooks/useRouterState.ts";
 export * from "./primitives/$page.ts";
 export * from "./providers/ReactPageProvider.ts";
+export * from "./providers/RootComponentsProvider.ts";
 export * from "./services/ReactPageService.ts";
 export * from "./services/ReactRouter.ts";

package/src/react/router/index.ts

@@ -15,6 +15,7 @@ import {
 import { ReactPreloadProvider } from "./providers/ReactPreloadProvider.ts";
 import { ReactServerProvider } from "./providers/ReactServerProvider.ts";
 import { ReactServerTemplateProvider } from "./providers/ReactServerTemplateProvider.ts";
+import { RouterLocaleProvider } from "./providers/RouterLocaleProvider.ts";
 import { SSRManifestProvider } from "./providers/SSRManifestProvider.ts";
 import { ReactPageServerService } from "./services/ReactPageServerService.ts";
 import { ReactPageService } from "./services/ReactPageService.ts";
@@ -28,6 +29,7 @@ export * from "./providers/ReactPageProvider.ts";
 export * from "./providers/ReactPreloadProvider.ts";
 export * from "./providers/ReactServerProvider.ts";
 export * from "./providers/ReactServerTemplateProvider.ts";
+export * from "./providers/RouterLocaleProvider.ts";
 export * from "./providers/SSRManifestProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -35,6 +37,11 @@ export * from "./providers/SSRManifestProvider.ts";
 declare module "alepha" {
   interface State {
     "alepha.react.router.state"?: ReactRouterState;
+    /**
+     * The active locale path-prefix (e.g. `"fr"`), when `routing: "prefix"` is
+     * enabled on the i18n module. Empty/absent for the default locale.
+     */
+    "alepha.react.router.locale"?: string;
   }
 
   interface Hooks {
@@ -124,6 +131,7 @@ export const AlephaReactRouter = $module({
     ReactRouter,
     ReactServerProvider,
     ReactServerTemplateProvider,
+    RouterLocaleProvider,
     SSRManifestProvider,
     ReactPageServerService,
   ],
@@ -143,6 +151,7 @@ export const AlephaReactRouter = $module({
       .with(ReactServerTemplateProvider)
       .with(ReactPreloadProvider)
       .with(ReactServerProvider)
+      .with(RouterLocaleProvider)
       .with(ReactPageProvider)
       .with(ReactRouter),
 });

package/src/react/router/primitives/$page.ts

@@ -54,8 +54,8 @@ import { ReactPageService } from "../services/ReactPageService.ts";
  * const userProfile = $page({
  *   path: "/users/:id",
  *   schema: {
- *     params: t.object({ id: t.integer() }),
- *     query: t.object({ tab: t.optional(t.text()) })
+ *     params: z.object({ id: z.integer() }),
+ *     query: z.object({ tab: z.text().optional() })
  *   },
  *   loader: async ({ params }) => {
  *     const user = await userApi.getUser(params.id);

package/src/react/router/providers/ReactBrowserProvider.ts

@@ -4,9 +4,10 @@ import {
   $inject,
   $state,
   Alepha,
+  SchemaValidator,
   type State,
   type Static,
-  t,
+  z,
 } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -26,8 +27,8 @@ export type { RouterPushOptions } from "../services/ReactRouter.ts";
  */
 export const reactBrowserOptions = $atom({
   name: "alepha.react.browser.options",
-  schema: t.object({
-    scrollRestoration: t.enum(["top", "manual"]), // TODO: must be per page?
+  schema: z.object({
+    scrollRestoration: z.enum(["top", "manual"]), // TODO: must be per page?
     /**
      * Intercept clicks on plain `<a href="/...">` anchors and route them
      * through the SPA router, so authors don't need `<Link>` everywhere
@@ -37,7 +38,7 @@ export const reactBrowserOptions = $atom({
      * `_self`, `download`, `data-no-router`, non-http(s) schemes, hash-only
      * hrefs, external origins, and clicks already `defaultPrevented`.
      */
-    interceptAnchorClicks: t.boolean({ default: true }),
+    interceptAnchorClicks: z.boolean().default(true),
   }),
   default: {
     scrollRestoration: "top" as const,
@@ -64,6 +65,7 @@ export class ReactBrowserProvider {
   protected readonly router = $inject(ReactBrowserRouterProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly browserHeadProvider = $inject(BrowserHeadProvider);
+  protected readonly validator = $inject(SchemaValidator);
 
   protected readonly options = $state(reactBrowserOptions);
 
@@ -136,7 +138,8 @@ export class ReactBrowserProvider {
   }
 
   public get url(): string {
-    const url = this.location.pathname + this.location.search;
+    const url =
+      this.location.pathname + this.location.search + this.location.hash;
     if (this.base) {
       return url.replace(this.base, "");
     }
@@ -205,8 +208,14 @@ export class ReactBrowserProvider {
     }
 
     // when redirecting in browser
-    if (this.state.url.pathname + this.state.url.search !== url) {
-      this.pushState(this.state.url.pathname + this.state.url.search);
+    // The hash is part of the identity of the committed route: without it,
+    // pushing "/docs#section" never matches "/docs" and takes the redirect
+    // branch below, which rewrites history without the fragment.
+    const committed =
+      this.state.url.pathname + this.state.url.search + this.state.url.hash;
+
+    if (committed !== url) {
+      this.pushState(committed);
       return;
     }
 
@@ -288,6 +297,53 @@ export class ReactBrowserProvider {
     }
   }
 
+  /**
+   * Apply the SSR hydration payload (the `#__ssr` script tag) to the atom
+   * store.
+   *
+   * Every key except `alepha.react.router.layers` is treated as an atom
+   * value. A registered atom's value is explicitly schema-validated: an
+   * invalid value is dropped (warn + keep the atom's default) instead of
+   * being trusted, so a tampered payload can't smuggle bad data into a
+   * validated atom. Atoms not registered yet fall through to
+   * `Alepha.set()`, which lets `StateManager.register()` decode them
+   * against the schema the moment they first get used.
+   *
+   * `alepha.react.router.layers` is deliberately skipped by this loop: it
+   * carries render instructions (`part`, `name`, `config`, `props`,
+   * `error`), not atom values. Those are NOT hardened here and are trusted
+   * as-is from the SSR payload — a tampered payload can still influence
+   * rendering through this key. Validating router layers is separate,
+   * future work; this method only guarantees atom values.
+   */
+  protected applyHydration(hydration: ReactHydrationState): void {
+    for (const [key, value] of Object.entries(hydration)) {
+      if (key === "alepha.react.router.layers") {
+        // Render instructions, not an atom value — see the method doc
+        // above. Intentionally trusted as-is.
+        continue;
+      }
+
+      const atom = this.alepha.store.getAtom(key);
+      if (atom) {
+        const result = this.validator.safeValidate(atom.schema, value);
+        if (!result.success) {
+          this.log.warn(
+            `Hydrated value for atom "${key}" failed schema validation, keeping default`,
+          );
+          continue;
+        }
+        this.alepha.store.set(key as keyof State, result.data as any, {
+          skipValidation: true,
+        });
+      } else {
+        // Not registered yet — register() will decode it when the atom
+        // first gets used.
+        this.alepha.set(key as keyof State, value);
+      }
+    }
+  }
+
   // -------------------------------------------------------------------------------------------------------------------
 
   protected readonly onTransitionEnd = $hook({
@@ -311,12 +367,7 @@ export class ReactBrowserProvider {
       const previous = hydration?.["alepha.react.router.layers"] ?? [];
 
       if (hydration) {
-        // low budget, but works for now
-        for (const [key, value] of Object.entries(hydration)) {
-          if (key !== "alepha.react.router.layers") {
-            this.alepha.set(key as keyof State, value);
-          }
-        }
+        this.applyHydration(hydration);
       }
 
       await this.render({ previous });