alepha 0.20.1 → 0.20.2

package/src/react/ui/atoms/uiAtom.ts

@@ -0,0 +1,28 @@
+import { $atom, type Static, t } from "alepha";
+
+/**
+ * Persisted UI state — color mode, theme palette, sidebar collapsed state, etc.
+ *
+ * The atom is bound to a single `alepha-ui` cookie via {@link UiPersistence},
+ * so values survive page reloads and are available during SSR.
+ */
+export const uiAtom = $atom({
+  name: "alepha.react.ui",
+  schema: t.object({
+    /** Color mode preference. `"system"` follows the OS-level setting. */
+    mode: t.enum(["light", "dark", "system"]),
+    /** Theme palette name. UI consumers map this to a CSS class on the root. */
+    theme: t.string(),
+    /** Sidebar UI state. */
+    sidebar: t.object({
+      collapsed: t.boolean(),
+    }),
+  }),
+  default: {
+    mode: "system",
+    theme: "default",
+    sidebar: { collapsed: false },
+  },
+});
+
+export type UiState = Static<typeof uiAtom.schema>;

package/src/react/ui/components/ColorScheme.tsx

@@ -0,0 +1,36 @@
+import { useEffect } from "react";
+import { useColorMode } from "../hooks/useColorMode.ts";
+import { useTheme } from "../hooks/useTheme.ts";
+
+/**
+ * Applies `class="dark"` and an optional theme palette class
+ * (`theme-<name>`) to the document root, syncing whenever the underlying
+ * atom mutates.
+ *
+ * Mount once near the root of your tree (typically inside the layout).
+ *
+ * @example
+ * <ColorScheme />
+ */
+export function ColorScheme() {
+  const { resolved } = useColorMode();
+  const { theme } = useTheme();
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    document.documentElement.classList.toggle("dark", resolved === "dark");
+  }, [resolved]);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    const previous: string[] = [];
+    root.classList.forEach((cls) => {
+      if (cls.startsWith("theme-")) previous.push(cls);
+    });
+    for (const cls of previous) root.classList.remove(cls);
+    if (theme && theme !== "default") root.classList.add(`theme-${theme}`);
+  }, [theme]);
+
+  return null;
+}

package/src/react/ui/hooks/useColorMode.ts

@@ -0,0 +1,49 @@
+import { useStore } from "alepha/react";
+import { useEffect, useState } from "react";
+import { uiAtom } from "../atoms/uiAtom.ts";
+
+export type ColorMode = "light" | "dark" | "system";
+export type ResolvedColorMode = "light" | "dark";
+
+/**
+ * Read and update the user's color-mode preference. `"system"` resolves to
+ * the OS preference and updates live as the OS toggles between light/dark.
+ *
+ * @example
+ * const { mode, setMode, resolved } = useColorMode();
+ * setMode("dark");
+ * document.documentElement.classList.toggle("dark", resolved === "dark");
+ */
+export const useColorMode = () => {
+  const [state, set] = useStore(uiAtom);
+  const mode = (state?.mode ?? "system") as ColorMode;
+  const resolved = useResolvedColorMode(mode);
+
+  return {
+    mode,
+    resolved,
+    setMode: (next: ColorMode) => {
+      set({ ...(state ?? uiAtom.options.default!), mode: next });
+    },
+  };
+};
+
+const useResolvedColorMode = (mode: ColorMode): ResolvedColorMode => {
+  const [systemDark, setSystemDark] = useState<boolean>(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia?.("(prefers-color-scheme: dark)").matches ?? false;
+  });
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const mq = window.matchMedia?.("(prefers-color-scheme: dark)");
+    if (!mq) return;
+    const onChange = (ev: MediaQueryListEvent) => setSystemDark(ev.matches);
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+
+  if (mode === "dark") return "dark";
+  if (mode === "light") return "light";
+  return systemDark ? "dark" : "light";
+};

package/src/react/ui/hooks/useSidebarState.ts

@@ -0,0 +1,26 @@
+import { useStore } from "alepha/react";
+import { uiAtom } from "../atoms/uiAtom.ts";
+
+/**
+ * Read and update the sidebar collapsed state. The value is persisted via the
+ * `alepha-ui` cookie so it survives reloads and is available during SSR — no
+ * flash of expanded-then-collapsed when the user prefers a collapsed shell.
+ *
+ * @example
+ * const { collapsed, setCollapsed, toggle } = useSidebarState();
+ */
+export const useSidebarState = () => {
+  const [state, set] = useStore(uiAtom);
+  const collapsed = state?.sidebar.collapsed ?? false;
+
+  const setCollapsed = (next: boolean) => {
+    const base = state ?? uiAtom.options.default!;
+    set({ ...base, sidebar: { ...base.sidebar, collapsed: next } });
+  };
+
+  return {
+    collapsed,
+    setCollapsed,
+    toggle: () => setCollapsed(!collapsed),
+  };
+};

package/src/react/ui/hooks/useTheme.ts

@@ -0,0 +1,22 @@
+import { useStore } from "alepha/react";
+import { uiAtom } from "../atoms/uiAtom.ts";
+
+/**
+ * Read and update the active theme palette name. UI consumers typically map
+ * the value to a class on the document root (e.g. `theme-claude`).
+ *
+ * @example
+ * const { theme, setTheme } = useTheme();
+ * setTheme("claude");
+ */
+export const useTheme = () => {
+  const [state, set] = useStore(uiAtom);
+  const theme = state?.theme ?? "default";
+
+  return {
+    theme,
+    setTheme: (next: string) => {
+      set({ ...(state ?? uiAtom.options.default!), theme: next });
+    },
+  };
+};

package/src/react/ui/index.ts

@@ -0,0 +1,35 @@
+import { $module } from "alepha";
+import type { UiState } from "./atoms/uiAtom.ts";
+import { UiPersistence } from "./services/UiPersistence.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./atoms/uiAtom.ts";
+export * from "./components/ColorScheme.tsx";
+export * from "./hooks/useColorMode.ts";
+export * from "./hooks/useSidebarState.ts";
+export * from "./hooks/useTheme.ts";
+export * from "./services/UiPersistence.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+declare module "alepha" {
+  export interface State {
+    "alepha.react.ui": UiState;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Persisted UI state: color mode, theme palette, sidebar collapsed state.
+ *
+ * Backed by an `alepha-ui` cookie so preferences survive reloads and are
+ * available during SSR (no flash of wrong theme).
+ *
+ * @module alepha.react.ui
+ */
+export const AlephaReactUi = $module({
+  name: "alepha.react.ui",
+  services: [UiPersistence],
+});

package/src/react/ui/services/UiPersistence.ts

@@ -0,0 +1,41 @@
+import { $head } from "alepha/react/head";
+import { $cookie } from "alepha/server/cookies";
+import { uiAtom } from "../atoms/uiAtom.ts";
+
+/**
+ * Inline `<script>` rendered by SSR into the document `<head>`. Runs
+ * synchronously before any CSS or React hydration: reads the `alepha-ui`
+ * cookie, resolves `mode === "system"` via `prefers-color-scheme`, and
+ * applies `class="dark"` (and optional `theme-<name>`) on `<html>`.
+ *
+ * This is what kills the flash-of-wrong-theme (FOUC) you'd otherwise get
+ * with React-effect-based theming. Failures are swallowed silently — at
+ * worst the page paints in light mode for one frame.
+ */
+const colorSchemeBoot = `(function(){try{var m=document.cookie.match(/(?:^|;\\s*)alepha-ui=([^;]+)/);var s=m?JSON.parse(decodeURIComponent(m[1])):{};var mode=s.mode||"system";var dark=mode==="dark"||(mode==="system"&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches);var r=document.documentElement;if(dark)r.classList.add("dark");if(s.theme&&s.theme!=="default")r.classList.add("theme-"+s.theme);}catch(e){}})();`;
+
+/**
+ * Binds the {@link uiAtom} to an `alepha-ui` cookie + injects an inline
+ * boot script into the SSR head to prevent FOUC on first paint.
+ *
+ * Reading flow: on app boot the cookie is parsed and pushed into the atom
+ * (via the `key` option on `$cookie`). Writing flow: every time the atom
+ * mutates, the cookie is rewritten — a single `useStore(uiAtom)` call is
+ * enough to persist UI preferences across reloads.
+ *
+ * Persists for 365 days; SameSite=lax so it travels on top-level navigation
+ * but not on cross-origin requests.
+ */
+export class UiPersistence {
+  ui = $cookie({
+    name: "alepha-ui",
+    key: uiAtom.key,
+    schema: uiAtom.schema,
+    ttl: [365, "days"],
+    sameSite: "lax",
+  });
+
+  head = $head({
+    script: [{ content: colorSchemeBoot }],
+  });
+}

package/src/router/TemplatedPathParser.ts

@@ -1,3 +1,5 @@
+import { AlephaError } from "alepha";
+
 /**
  * Parses and manipulates templated paths with `{param}` placeholders.
  *
@@ -23,26 +25,25 @@
 export class TemplatedPathParser {
   protected static readonly PARAM_REGEX = /\{([^}]+)\}/g;
 
-  protected readonly template: string;
-  protected readonly separator: string;
+  public readonly template: string;
+  public readonly separator: string;
+  public readonly paramNames: readonly string[];
+  public readonly hasParams: boolean;
+  protected readonly extractRegex: RegExp | null;
 
   constructor(template: string, separator = "/") {
+    if (separator.length !== 1) {
+      throw new AlephaError(
+        `TemplatedPathParser separator must be a single character, got '${separator}'`,
+      );
+    }
     this.template = template;
     this.separator = separator;
-  }
-
-  /**
-   * Returns true if the template contains at least one `{param}` placeholder.
-   */
-  get hasParams(): boolean {
-    return /\{[^}]+\}/.test(this.template);
-  }
-
-  /**
-   * Returns an ordered list of parameter names found in the template.
-   */
-  get paramNames(): string[] {
-    return [...this.template.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+    this.paramNames = [
+      ...template.matchAll(TemplatedPathParser.PARAM_REGEX),
+    ].map((m) => m[1]);
+    this.hasParams = this.paramNames.length > 0;
+    this.extractRegex = this.hasParams ? this.buildExtractRegex() : null;
   }
 
   /**
@@ -51,50 +52,31 @@ export class TemplatedPathParser {
    */
   interpolate(params: Record<string, string>): string {
     return this.template.replace(
-      /\{([^}]+)\}/g,
+      TemplatedPathParser.PARAM_REGEX,
       (_, name: string) => params[name] ?? `{${name}}`,
     );
   }
 
   /**
    * Extracts parameter values from a concrete path by matching it against
-   * the template structure. Returns an empty object when the template has
-   * no parameters.
+   * the template structure.
+   *
+   * Returns `null` when the path does not match the template.
+   * Returns `{}` when the template has no parameters and the path matches.
    */
-  extract(path: string): Record<string, string> {
-    const names = this.paramNames;
-    if (names.length === 0) {
-      return {};
+  extract(path: string): Record<string, string> | null {
+    if (!this.extractRegex) {
+      return path === this.template ? {} : null;
     }
 
-    const escapedSeparator = this.separator.replace(
-      /[.*+?^${}()|[\]\\]/g,
-      "\\$&",
-    );
-
-    // Build a regex from the template: escape literal parts, replace {param} with a capture group
-    const regexSource = this.template
-      .replace(/[.*+?^${}()|[\]\\]/g, (char) => {
-        // Allow { and } through so we can then replace them as param groups
-        if (char === "{" || char === "}") {
-          return char;
-        }
-        return `\\${char}`;
-      })
-      // After escaping literal chars, replace {name} patterns with capture groups.
-      // The separator is already escaped above, so we match anything that is not the separator.
-      .replace(/\{([^}]+)\}/g, `([^${escapedSeparator}]+)`);
-
-    const regex = new RegExp(`^${regexSource}$`);
-    const match = regex.exec(path);
-
+    const match = this.extractRegex.exec(path);
     if (!match) {
-      return {};
+      return null;
     }
 
     const result: Record<string, string> = {};
-    for (let i = 0; i < names.length; i++) {
-      result[names[i]] = match[i + 1];
+    for (let i = 0; i < this.paramNames.length; i++) {
+      result[this.paramNames[i]] = match[i + 1];
     }
     return result;
   }
@@ -104,7 +86,7 @@ export class TemplatedPathParser {
    * wildcard string. Defaults to `"+"` (MQTT-style).
    */
   wildcardize(wildcard = "+"): string {
-    return this.template.replace(/\{[^}]+\}/g, wildcard);
+    return this.template.replace(TemplatedPathParser.PARAM_REGEX, wildcard);
   }
 
   /**
@@ -113,16 +95,33 @@ export class TemplatedPathParser {
    */
   normalize(path: string): string {
     const sep = this.separator;
-    const escapedSep = sep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escapedSep = this.escapeRegex(sep);
 
-    // Replace consecutive separators with a single one
     let result = path.replace(new RegExp(`${escapedSep}{2,}`, "g"), sep);
 
-    // Strip trailing separator, but preserve a lone separator
     if (result.endsWith(sep) && result.length > sep.length) {
       result = result.slice(0, -sep.length);
     }
 
     return result;
   }
+
+  protected buildExtractRegex(): RegExp {
+    const escapedSeparator = this.escapeRegex(this.separator);
+
+    const regexSource = this.template
+      .replace(/[.*+?^${}()|[\]\\]/g, (char) => {
+        if (char === "{" || char === "}") {
+          return char;
+        }
+        return `\\${char}`;
+      })
+      .replace(/\{[^}]+\}/g, `([^${escapedSeparator}]+)`);
+
+    return new RegExp(`^${regexSource}$`);
+  }
+
+  protected escapeRegex(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
 }

package/src/router/__tests__/RouterProvider.spec.ts

@@ -177,6 +177,68 @@ describe("RouterProvider", () => {
     });
   });
 
+  it("should return a fresh params object on each match (no shared mutation)", ({
+    expect,
+  }) => {
+    const { add, router } = playground();
+    add("/users/:id", "user");
+
+    const a = router.match("/users/42");
+    const b = router.match("/users/42");
+    expect(a.params).not.toBe(b.params);
+    a.params!.injected = "x";
+    expect(b.params).toEqual({ id: "42" });
+  });
+
+  it("should cache by pathname only (ignoring query string)", ({ expect }) => {
+    const { add, router } = playground();
+    add("/search", "search");
+
+    router.match("/search?q=1");
+    router.match("/search?q=2");
+    router.match("/search?q=3");
+    // cache is protected; assert via Map size on the subclass
+    expect(
+      (router as unknown as { cache: Map<string, unknown> }).cache.size,
+    ).toBe(1);
+  });
+
+  it("should cap the cache size to avoid unbounded growth", ({ expect }) => {
+    const { add, router } = playground();
+    add("/*", "catchall");
+
+    (router as unknown as { maxCacheSize: number }).maxCacheSize = 5;
+    for (let i = 0; i < 20; i++) {
+      router.match(`/x/${i}`);
+    }
+    const size = (router as unknown as { cache: Map<string, unknown> }).cache
+      .size;
+    expect(size).toBeLessThanOrEqual(5);
+  });
+
+  it("should invalidate the cache when a new route is pushed", ({ expect }) => {
+    const { add, router } = playground();
+    const m1 = router.match("/new");
+    expect(m1.route).toBeUndefined();
+
+    add("/new", "new-route");
+    const m2 = router.match("/new");
+    expect(m2.route?.name).toBe("new-route");
+  });
+
+  it("should handle three-way conflicting param names at the same level", ({
+    expect,
+  }) => {
+    const { add, match } = playground();
+    add("/u/:a", "a-route");
+    add("/u/:b/x", "b-route");
+    add("/u/:c/y", "c-route");
+
+    expect(match("/u/1")).toEqual({ name: "a-route", params: { a: "1" } });
+    expect(match("/u/1/x")).toEqual({ name: "b-route", params: { b: "1" } });
+    expect(match("/u/1/y")).toEqual({ name: "c-route", params: { c: "1" } });
+  });
+
   it("should handle routes with different param names", ({ expect }) => {
     const { add, match } = playground();
     add("/users/:id", "home");

package/src/router/__tests__/TemplatedPathParser.spec.ts

@@ -120,6 +120,24 @@ describe("TemplatedPathParser", () => {
         deviceId: "device-1",
       });
     });
+
+    it("returns null when the path does not match the template", () => {
+      const parser = new TemplatedPathParser("/users/{id}");
+      expect(parser.extract("/posts/42")).toBeNull();
+      expect(parser.extract("/users/42/extra")).toBeNull();
+    });
+
+    it("returns null for a parameterless template when path differs", () => {
+      const parser = new TemplatedPathParser("/users/profile");
+      expect(parser.extract("/users/other")).toBeNull();
+    });
+  });
+
+  describe("constructor validation", () => {
+    it("throws when separator is not a single character", () => {
+      expect(() => new TemplatedPathParser("foo", "::")).toThrow();
+      expect(() => new TemplatedPathParser("foo", "")).toThrow();
+    });
   });
 
   describe("wildcardize", () => {

package/src/router/providers/RouterProvider.ts

@@ -5,14 +5,18 @@ export abstract class RouterProvider<T extends Route = Route> {
 
   protected tree: Tree<T> = { children: {} };
   protected cache = new Map<string, RouteMatch<T>>();
+  protected maxCacheSize = 10_000;
 
   public match(path: string): RouteMatch<T> {
-    if (this.cache.has(path)) {
-      return this.cache.get(path)!;
+    const pathname = path.split("?", 1)[0];
+    const hit = this.cache.get(pathname);
+    if (hit) {
+      return { route: hit.route, params: { ...hit.params } };
     }
-    const result = this.mapParams(this.createRouteMatch(path));
-    this.cache.set(path, result);
-    return result;
+    const result = this.mapParams(this.createRouteMatch(pathname));
+    if (this.cache.size >= this.maxCacheSize) this.cache.clear();
+    this.cache.set(pathname, result);
+    return { route: result.route, params: { ...result.params } };
   }
 
   protected test(path: string): void {
@@ -25,6 +29,7 @@ export abstract class RouterProvider<T extends Route = Route> {
     const path = route.path.replaceAll("//", "/");
 
     this.test(path);
+    this.cache.clear();
 
     const parts = this.createParts(path);
 

package/src/system/providers/NodeShellProvider.ts

@@ -115,6 +115,7 @@ export class NodeShellProvider implements ShellProvider {
         command,
         {
           cwd: options.cwd,
+          maxBuffer: 50 * 1024 * 1024,
           env: {
             ...process.env,
             LOG_FORMAT: "pretty",

package/src/topic/core/providers/TopicProvider.ts

@@ -112,7 +112,7 @@ export abstract class TopicProvider {
           const parsed = this.parseMessage<T>(schema, message);
 
           if (parser.hasParams && receivedTopic) {
-            const params = parser.extract(receivedTopic);
+            const params = parser.extract(receivedTopic) ?? {};
             await handler({ ...parsed, params } as TopicMessage<T>);
           } else {
             await handler(parsed);