alepha 0.23.0 → 0.24.0

package/src/react/i18n/providers/I18nProvider.ts

@@ -1,4 +1,4 @@
-import { $hook, $inject, Alepha, TypeBoxError, TypeProvider, t } from "alepha";
+import { $hook, $inject, Alepha, TypeBoxError, TypeProvider, z } from "alepha";
 import { type DateTime, DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 // Locale-prefix routing is optional: the router module (one-directional
@@ -17,7 +17,7 @@ export class I18nProvider<
 
   protected cookie = $cookie({
     name: "lang",
-    schema: t.text(),
+    schema: z.text(),
     ttl: [1, "year"],
   });
 

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

@@ -1,5 +1,5 @@
 import { waitFor } from "@testing-library/dom";
-import { Alepha, createMiddleware, type Middleware, t } from "alepha";
+import { Alepha, createMiddleware, type Middleware, z } from "alepha";
 import { AlephaReact } from "alepha/react";
 import { act } from "react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -90,8 +90,8 @@ describe("$page browser tests", () => {
         user = $page({
           path: "/user/:id",
           schema: {
-            params: t.object({
-              id: t.text(),
+            params: z.object({
+              id: z.text(),
             }),
           },
           loader: ({ params }) => ({
@@ -648,8 +648,8 @@ describe("$page browser tests", () => {
         user = $page({
           path: "/user/:id",
           schema: {
-            params: t.object({
-              id: t.text(),
+            params: z.object({
+              id: z.text(),
             }),
           },
           loader: ({ params }) => ({
@@ -682,9 +682,9 @@ describe("$page browser tests", () => {
         search = $page({
           path: "/search",
           schema: {
-            query: t.object({
-              q: t.text({ default: "" }),
-              page: t.number({ default: 1 }),
+            query: z.object({
+              q: z.text({ default: "" }),
+              page: z.number().default(1),
             }),
           },
           loader: ({ query }) => ({
@@ -731,9 +731,9 @@ describe("$page browser tests", () => {
         search = $page({
           path: "/search",
           schema: {
-            query: t.object({
-              q: t.text({ default: "" }),
-              page: t.number({ default: 1 }),
+            query: z.object({
+              q: z.text({ default: "" }),
+              page: z.number().default(1),
             }),
           },
           loader: ({ query }) => ({
@@ -780,12 +780,12 @@ describe("$page browser tests", () => {
         userPosts = $page({
           path: "/users/:userId/posts",
           schema: {
-            params: t.object({
-              userId: t.text(),
+            params: z.object({
+              userId: z.text(),
             }),
-            query: t.object({
-              sort: t.text({ default: "recent" }),
-              limit: t.number({ default: 10 }),
+            query: z.object({
+              sort: z.text({ default: "recent" }),
+              limit: z.number().default(10),
             }),
           },
           loader: ({ params, query }) => ({
@@ -838,9 +838,9 @@ describe("$page browser tests", () => {
         search = $page({
           path: "/search",
           schema: {
-            query: t.object({
-              q: t.text({ default: "default search" }),
-              page: t.number({ default: 1 }),
+            query: z.object({
+              q: z.text({ default: "default search" }),
+              page: z.number().default(1),
             }),
           },
           loader: ({ query }) => ({

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/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/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 });

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

@@ -5,10 +5,11 @@ import {
   $state,
   Alepha,
   AlephaError,
+  coerceObject,
   OPTIONS,
   PipelineHandler,
   type TSchema,
-  t,
+  z,
 } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -35,11 +36,11 @@ import { RouterLocaleProvider } from "./RouterLocaleProvider.ts";
 export const reactPageOptions = $atom({
   name: "alepha.react.page.options",
   description: "Configuration options for the React page provider.",
-  schema: t.object({
+  schema: z.object({
     /**
      * Enable React StrictMode wrapper.
      */
-    strictMode: t.boolean({ default: true }),
+    strictMode: z.boolean().default(true),
     /**
      * RegExp pattern (as string) to detect file-like URLs (e.g. /hello.txt, /wp-login.php).
      * When a request hits the catch-all wildcard route and matches this pattern,
@@ -49,7 +50,7 @@ export const reactPageOptions = $atom({
      *
      * @default "\\.[a-zA-Z0-9]{1,10}$"
      */
-    staticFilePattern: t.string(),
+    staticFilePattern: z.string(),
   }),
   default: {
     strictMode: true,
@@ -264,15 +265,16 @@ export class ReactPageProvider {
     schema?: TSchema,
     value?: any,
   ): any => {
-    if (t.schema.isObject(schema) && typeof value === "object") {
+    if (z.schema.isObject(schema) && typeof value === "object") {
       for (const key in schema.properties) {
-        if (
-          t.schema.isObject(schema.properties[key]) &&
-          typeof value[key] === "string"
-        ) {
+        // Peel optional/nullable/default wrappers so a field declared as
+        // `z.object(...).optional()` is still recognised as an object whose
+        // JSON-encoded query value needs parsing.
+        const propSchema = z.schema.unwrap(schema.properties[key]);
+        if (z.schema.isObject(propSchema) && typeof value[key] === "string") {
           try {
             value[key] = this.alepha.codec.decode(
-              schema.properties[key],
+              propSchema,
               decodeURIComponent(value[key]),
             );
           } catch (e) {
@@ -313,7 +315,13 @@ export class ReactPageProvider {
       try {
         this.convertStringObjectToObject(route.schema?.query, state.query);
         config.query = route.schema?.query
-          ? this.alepha.codec.decode(route.schema.query, state.query)
+          ? this.alepha.codec.decode(
+              route.schema.query,
+              // Query params arrive as strings from the URL; coerce declared
+              // scalar fields (number/integer/boolean) to their schema type
+              // before strict validation, mirroring the HTTP server boundary.
+              coerceObject(route.schema.query, state.query),
+            )
           : {};
       } catch (e) {
         it.error = e instanceof Error ? e : new Error(String(e));
@@ -322,7 +330,13 @@ export class ReactPageProvider {
 
       try {
         config.params = route.schema?.params
-          ? this.alepha.codec.decode(route.schema.params, state.params)
+          ? this.alepha.codec.decode(
+              route.schema.params,
+              // URL path params arrive as strings; coerce declared scalar
+              // fields (number/integer/boolean) to their schema type before
+              // strict validation, mirroring `query` above and the HTTP server.
+              coerceObject(route.schema.params, state.params),
+            )
           : {};
       } catch (e) {
         it.error = e instanceof Error ? e : new Error(String(e));