zudoku 0.0.0-f40ea27 → 0.0.0-f42e3678

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.0.0-f40ea27",
+  "version": "0.0.0-f42e3678",
   "type": "module",
   "homepage": "https://zudoku.dev",
   "repository": {
@@ -133,13 +133,13 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "12.0.2",
-    "@envelop/core": "5.2.3",
+    "@envelop/core": "5.3.0",
     "@graphql-typed-document-node/core": "3.2.0",
     "@hookform/resolvers": "4.1.3",
-    "@lekoarts/rehype-meta-as-attributes": "3.0.2",
+    "@lekoarts/rehype-meta-as-attributes": "3.0.3",
     "@mdx-js/react": "3.1.0",
     "@mdx-js/rollup": "3.1.0",
-    "@pothos/core": "4.6.0",
+    "@pothos/core": "4.7.0",
     "@radix-ui/react-accordion": "1.2.11",
     "@radix-ui/react-alert-dialog": "1.1.14",
     "@radix-ui/react-aspect-ratio": "1.1.7",
@@ -162,21 +162,21 @@
     "@radix-ui/react-toggle-group": "1.1.10",
     "@radix-ui/react-tooltip": "1.2.7",
     "@radix-ui/react-visually-hidden": "1.2.3",
-    "@scalar/openapi-parser": "0.10.17",
+    "@scalar/openapi-parser": "0.18.0",
     "@sentry/node": "9.26.0",
-    "@shikijs/langs": "3.5.0",
-    "@shikijs/rehype": "3.5.0",
-    "@shikijs/themes": "3.5.0",
-    "@shikijs/transformers": "3.5.0",
+    "@shikijs/langs": "3.7.0",
+    "@shikijs/rehype": "3.7.0",
+    "@shikijs/themes": "3.7.0",
+    "@shikijs/transformers": "3.7.0",
     "@sindresorhus/slugify": "2.2.1",
     "@stefanprobst/rehype-extract-toc": "3.0.0",
     "@tailwindcss/typography": "0.5.16",
-    "@tailwindcss/vite": "4.1.7",
+    "@tailwindcss/vite": "4.1.11",
     "@tanem/react-nprogress": "5.0.55",
-    "@tanstack/react-query": "5.74.3",
+    "@tanstack/react-query": "5.81.5",
     "@types/react": "19.1.8",
     "@types/react-dom": "19.1.6",
-    "@vitejs/plugin-react": "4.4.1",
+    "@vitejs/plugin-react": "4.6.0",
     "@zudoku/httpsnippet": "10.0.9",
     "@zudoku/react-helmet-async": "2.0.5",
     "allof-merge": "0.6.6",
@@ -195,7 +195,7 @@
     "glob-parent": "6.0.2",
     "graphql": "16.11.0",
     "graphql-type-json": "0.3.2",
-    "graphql-yoga": "5.13.5",
+    "graphql-yoga": "5.14.0",
     "gray-matter": "4.0.3",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "hast-util-to-string": "3.0.1",
@@ -203,24 +203,24 @@
     "http-terminator": "3.2.0",
     "json-schema-to-typescript-lite": "14.1.0",
     "loglevel": "1.9.2",
-    "lru-cache": "11.0.2",
-    "lucide-react": "0.515.0",
+    "lru-cache": "11.1.0",
+    "lucide-react": "0.525.0",
     "minimatch": "10.0.1",
-    "motion": "12.0.0-alpha.2",
+    "motion": "12.23.3",
     "nanoevents": "^9.1.0",
-    "next-themes": "0.4.4",
+    "next-themes": "0.4.6",
     "oauth4webapi": "2.17.0",
     "object-hash": "3.0.0",
     "openapi-types": "12.1.3",
     "pagefind": "1.4.0-alpha.1",
     "picocolors": "1.1.1",
-    "piscina": "5.0.0",
+    "piscina": "5.1.3",
     "posthog-node": "4.17.1",
-    "react-error-boundary": "5.0.0",
-    "react-hook-form": "7.57.0",
+    "react-error-boundary": "6.0.0",
+    "react-hook-form": "7.60.0",
     "react-is": "19.1.0",
     "react-markdown": "10.1.0",
-    "react-router": "7.6.1",
+    "react-router": "7.6.3",
     "rehype-mdx-import-media": "1.2.0",
     "rehype-raw": "7.0.0",
     "rehype-slug": "6.0.0",
@@ -229,17 +229,17 @@
     "remark-directive-rehype": "0.4.2",
     "remark-frontmatter": "5.0.0",
     "remark-gfm": "4.0.1",
-    "remark-mdx-frontmatter": "5.1.0",
+    "remark-mdx-frontmatter": "5.2.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
-    "rollup": "4.41.1",
-    "semver": "7.7.1",
-    "shiki": "3.5.0",
+    "rollup": "4.45.0",
+    "semver": "7.7.2",
+    "shiki": "3.7.0",
     "sitemap": "8.0.0",
     "spin-delay": "2.0.1",
     "strip-ansi": "7.1.0",
-    "tailwind-merge": "3.3.0",
-    "tailwindcss": "4.1.7",
+    "tailwind-merge": "3.3.1",
+    "tailwindcss": "4.1.11",
     "ulidx": "2.4.1",
     "unified": "^11.0.5",
     "unist-util-visit": "5.0.0",
@@ -247,18 +247,19 @@
     "vfile": "6.0.3",
     "vite": "6.3.5",
     "yaml": "2.8.0",
-    "yargs": "17.7.2",
-    "zod": "3.25.56",
+    "yargs": "18.0.0",
+    "zod": "3.25.74",
     "zod-to-ts": "1.2.0",
     "zustand": "5.0.5"
   },
   "devDependencies": {
     "@graphql-codegen/cli": "5.0.7",
     "@graphql-codegen/client-preset": "4.8.2",
+    "@inkeep/cxkit-types": "0.5.90",
     "@testing-library/dom": "10.4.0",
     "@testing-library/jest-dom": "6.6.3",
     "@testing-library/react": "16.3.0",
-    "@types/estree": "1.0.7",
+    "@types/estree": "1.0.8",
     "@types/express": "5.0.2",
     "@types/glob-parent": "5.1.3",
     "@types/har-format": "1.2.16",
@@ -274,14 +275,14 @@
     "@types/yargs": "17.0.33",
     "@vitest/coverage-v8": "3.2.1",
     "esbuild": "0.25.1",
-    "happy-dom": "17.5.6",
+    "happy-dom": "18.0.1",
     "mdast-util-mdx": "3.0.0",
     "react": "19.1.0",
     "react-dom": "19.1.0",
-    "rollup-plugin-visualizer": "5.14.0",
+    "rollup-plugin-visualizer": "6.0.3",
     "tsx": "4.19.4",
     "typescript": "5.8.3",
-    "vitest": "3.2.3"
+    "vitest": "3.2.4"
   },
   "peerDependencies": {
     "@azure/msal-browser": "^4.13.0",

package/src/app/demo.tsx

@@ -10,6 +10,10 @@ import "./main.css";
 import { getRoutesByConfig } from "./main.js";
 
 const apiUrl = new URL(window.location.href).searchParams.get("api-url");
+const logoUrl = new URL(window.location.href).searchParams.get("logo-url");
+const logoWidth = new URL(window.location.href).searchParams.get("logo-width");
+const title =
+  new URL(window.location.href).searchParams.get("title") ?? "Zudoku Demo";
 
 if (!apiUrl) {
   throw new Error(
@@ -29,9 +33,9 @@ if (!root) {
 // IMPORTANT: This component must not contain tailwind classes
 // This directory is not processed by the tailwind plugin
 
-const config = {
+const config: ZudokuConfig = {
   site: {
-    title: "",
+    title,
     banner: {
       message: <DemoAnnouncement />,
     },
@@ -53,6 +57,19 @@ const config = {
   ],
 } satisfies ZudokuConfig;
 
+if (logoUrl && logoWidth) {
+  config.site = {
+    ...config.site,
+    logo: {
+      src: {
+        light: logoUrl,
+        dark: logoUrl,
+      },
+      width: logoWidth,
+    },
+  };
+}
+
 const routes = getRoutesByConfig(config);
 const router = createBrowserRouter(routes, {
   basename: window.location.pathname,

package/src/app/main.css

@@ -121,6 +121,10 @@
   .shiki {
     counter-reset: line;
     @apply leading-normal;
+    background-color: var(--shiki-light-bg) !important;
+  }
+  .dark .shiki {
+    background-color: var(--shiki-dark-bg) !important;
   }
   .code-block .shiki {
     @apply grid grid-rows-1;
@@ -149,17 +153,34 @@
     @apply tabular-nums inline-flex items-baseline justify-end me-4 w-3 text-muted-foreground/25;
   }
 
-  .shiki.not-inline .line {
+  .light .shiki.not-inline .line {
     @apply block -mx-4 px-4 w-[calc(100%+2rem)];
-    --highlighted-bg: hsl(
-      from var(--muted) h s calc(l + 4 * var(--dark)) / 50%
-    );
+    --highlighted-bg: hsl(from var(--shiki-light-bg) h s calc(l - 6));
   }
+  .dark .shiki.not-inline .line {
+    @apply block -mx-4 px-4 w-[calc(100%+2rem)];
+    --highlighted-bg: hsl(from var(--shiki-dark-bg) h s calc(l + 10));
+  }
+
   .shiki .line.highlighted {
-    @apply bg-(--highlighted-bg);
+    @apply bg-(--highlighted-bg) relative;
+  }
+
+  .shiki .line.highlighted:before {
+    position: absolute;
+    inset-inline-start: 0;
+    inset-block-start: 0;
+    inset-block-end: 0;
+    border-left: 2px solid
+      hsl(from var(--highlighted-bg) h s calc(l + 4 * var(--dark)));
+    content: "";
   }
 
   .shiki .highlighted-word {
+    --highlighted-bg: hsl(
+      from var(--muted) h s calc(l + 4 * var(--dark)) / 50%
+    );
+
     @apply bg-(--highlighted-bg) px-0.5 rounded;
     box-shadow: 0 0 0 4px var(--highlighted-bg);
   }

package/src/app/main.tsx

@@ -82,22 +82,13 @@ export const getRoutesByOptions = (
     .flatMap((plugin) => (isNavigationPlugin(plugin) ? plugin.getRoutes() : []))
     .concat(
       enableStatusPages
-        ? [400, 403, 404, 405, 414, 416, 500, 501, 502, 503, 504].map(
-            (statusCode) => ({
-              path: `/${statusCode}`,
-              element: <StatusPage statusCode={statusCode} />,
-            }),
-          )
+        ? [400, 404, 500].map((statusCode) => ({
+            path: `/${statusCode}`,
+            element: <StatusPage statusCode={statusCode} />,
+          }))
         : [],
     )
-    .concat([
-      {
-        path: "*",
-        loader: () => {
-          throw new Response("Not Found", { status: 404 });
-        },
-      },
-    ]);
+    .concat([{ path: "*", element: <StatusPage statusCode={404} /> }]);
 
   // @TODO Detect conflicts in routes and log warning
 
@@ -125,6 +116,7 @@ export const getRoutesByConfig = (config: ZudokuConfig): RouteObject[] => {
           <Layout />
         </Zudoku>
       ),
+      hydrateFallbackElement: <div>Loading...</div>,
       children: [
         {
           element: <RouteGuard />,

package/src/lib/authentication/authentication.ts

@@ -1,6 +1,6 @@
 export interface AuthenticationPlugin {
-  signUp(options?: { redirectTo?: string }): Promise<void>;
-  signIn(options?: { redirectTo?: string }): Promise<void>;
+  signUp(options?: { redirectTo?: string; replace?: boolean }): Promise<void>;
+  signIn(options?: { redirectTo?: string; replace?: boolean }): Promise<void>;
   signOut(): Promise<void>;
   // @deprecated use signRequest instead
   getAccessToken(): Promise<string>;

package/src/lib/authentication/components/CallbackHandler.tsx

@@ -1,9 +1,9 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
 import { Navigate } from "react-router";
 import { useZudoku } from "zudoku/components";
-import { ZudokuError } from "../../util/invariant.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { normalizeRedirectUrl } from "../../util/url.js";
+import { OAuthAuthorizationError, type OAuthErrorType } from "../errors.js";
 
 export function CallbackHandler({
   handleCallback,
@@ -15,22 +15,29 @@ export function CallbackHandler({
     retry: false,
     queryKey: ["oauth-callback"],
     queryFn: async () => {
-      try {
-        return joinUrl(
-          normalizeRedirectUrl(
-            await handleCallback(),
-            window.location.origin,
-            options.basePath,
-          ),
+      const url = new URL(window.location.href);
+
+      const errorParam = url.searchParams.get("error");
+      const errorDescription =
+        url.searchParams.get("error_description") ?? undefined;
+      const errorUri = url.searchParams.get("error_uri") ?? undefined;
+      if (errorParam) {
+        throw new OAuthAuthorizationError(
+          `OAuth error '${errorParam}': ${errorDescription}`,
+          {
+            error: errorParam as OAuthErrorType,
+            error_description: errorDescription,
+            error_uri: errorUri,
+          },
         );
-      } catch (error) {
-        throw new ZudokuError("Could not validate user", {
-          cause: error,
-          title: "Authentication Error",
-          developerHint:
-            "Check the configuration of your authorization provider and ensure all settings such as the callback URL are configured correctly.",
-        });
       }
+      return joinUrl(
+        normalizeRedirectUrl(
+          await handleCallback(),
+          window.location.origin,
+          options.basePath,
+        ),
+      );
     },
   });
 

package/src/lib/authentication/components/OAuthErrorPage.tsx

@@ -0,0 +1,171 @@
+import { HomeIcon } from "lucide-react";
+import { Link } from "react-router";
+import { Heading } from "../../components/Heading.js";
+import { Typography } from "../../components/Typography.js";
+import { Button } from "../../ui/Button.js";
+import { OAuthAuthorizationError } from "../errors.js";
+import { useAuth } from "../hook.js";
+
+const errorDetailsMap: Record<string, { message: string }> = {
+  invalid_request: {
+    message:
+      "The authentication request was invalid. Please try signing in again.",
+  },
+  unauthorized_client: {
+    message:
+      "This application is not authorized to access your account. Please contact support.",
+  },
+  access_denied: {
+    message:
+      "You denied access to this application. To continue, please sign in and grant access.",
+  },
+  unsupported_response_type: {
+    message:
+      "The authentication method is not supported. Please contact support.",
+  },
+  invalid_scope: {
+    message: "The requested permissions are invalid. Please contact support.",
+  },
+  server_error: {
+    message:
+      "The authentication server encountered an error. Please try again in a few moments.",
+  },
+  temporarily_unavailable: {
+    message:
+      "The authentication service is temporarily unavailable. Please try again in a few moments.",
+  },
+  // Token errors
+  invalid_client: {
+    message: "Invalid application credentials. Please contact support.",
+  },
+  invalid_grant: {
+    message:
+      "The authentication code has expired or is invalid. Please sign in again.",
+  },
+  unsupported_grant_type: {
+    message:
+      "The authentication method is not supported. Please contact support.",
+  },
+  // Custom errors
+  invalid_state: {
+    message:
+      "Security validation failed. This may be due to a potential security attack. Please try signing in again.",
+  },
+  missing_code_verifier: {
+    message:
+      "Authentication security information is missing. Please clear your browser cache and try again.",
+  },
+  network_error: {
+    message:
+      "A network error occurred during authentication. Please check your connection and try again.",
+  },
+  token_expired: {
+    message: "Your authentication session has expired. Please sign in again.",
+  },
+  configuration_error: {
+    message:
+      "There is an issue with the authentication configuration. Please contact support.",
+  },
+  unknown_error: {
+    message:
+      "An unexpected error occurred during authentication. Please try again or contact support.",
+  },
+};
+
+export function OAuthErrorPage({ error }: { error: any }) {
+  const { login } = useAuth();
+
+  if (!(error instanceof OAuthAuthorizationError)) {
+    throw error;
+  }
+
+  const oauthError = error.error;
+  const type = oauthError.error;
+
+  const details = errorDetailsMap[type] ?? errorDetailsMap.unknown_error;
+
+  return (
+    <div className="min-h-[400px] flex items-center justify-center p-4">
+      <div className="max-w-md w-full text-center space-y-6">
+        <div className="space-y-4 items-center">
+          <Heading level={2} className="text-2xl inline-block font-bold">
+            {titles[type] || "Authentication Error"}
+          </Heading>
+
+          <Typography className="text-gray-600 dark:text-gray-300 leading-relaxed">
+            {details?.message}
+          </Typography>
+
+          {/* Technical details for developers (only in development) */}
+        </div>
+
+        {/* Action Buttons */}
+        <div className="space-y-3 pt-4">
+          <div className="space-y-2">
+            {(type === "access_denied" ||
+              type === "invalid_grant" ||
+              type === "token_expired") && (
+              <Button
+                onClick={login}
+                className="w-full capitalize"
+                variant={"default"}
+              >
+                Sign in again
+              </Button>
+            )}
+          </div>
+
+          <div className="flex gap-2">
+            <Button asChild className="flex-1" variant="outline">
+              <Link to="/">
+                <HomeIcon className="w-4 h-4 mr-2" />
+                Go Home
+              </Link>
+            </Button>
+          </div>
+        </div>
+
+        {/* Additional Help */}
+        {helpMessages[type] && (
+          <Typography className="text-sm text-gray-500 dark:text-gray-400">
+            {helpMessages[type]}
+          </Typography>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const titles: Record<string, string> = {
+  access_denied: "Access Denied",
+  invalid_request: "Invalid Request",
+  unauthorized_client: "Unauthorized Application",
+  unsupported_response_type: "Unsupported Method",
+  invalid_scope: "Invalid Permissions",
+  server_error: "Server Error",
+  temporarily_unavailable: "Service Unavailable",
+  invalid_client: "Invalid Credentials",
+  invalid_grant: "Authentication Expired",
+  unsupported_grant_type: "Unsupported Authentication",
+  invalid_state: "Security Check Failed",
+  missing_code_verifier: "Security Information Missing",
+  network_error: "Network Error",
+  token_expired: "Session Expired",
+  configuration_error: "Configuration Error",
+  unknown_error: "Authentication Failed",
+};
+
+const helpMessages: Record<string, string> = {
+  access_denied:
+    "If you changed your mind, you can try signing in again to grant access.",
+  invalid_state:
+    "This error can occur if you have multiple tabs open or if your session was compromised.",
+  missing_code_verifier:
+    "Try clearing your browser's cache and cookies for this site.",
+  network_error:
+    "Check your internet connection and ensure you can access other websites.",
+  server_error:
+    "The issue is on our end. Our team has been notified and is working to fix it.",
+  temporarily_unavailable:
+    "This is usually temporary. Try again in a few minutes.",
+};

package/src/lib/authentication/components/SignIn.tsx

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
-import { Link, useSearchParams } from "react-router";
-import { Button } from "zudoku/ui/Button.js";
+import { useSearchParams } from "react-router";
+import { Spinner } from "zudoku/components";
 import {
   Card,
   CardContent,
@@ -16,6 +16,7 @@ export const SignIn = () => {
   useEffect(() => {
     void context.authentication?.signIn({
       redirectTo: search.get("redirect") ?? undefined,
+      replace: true,
     });
   }, [context.authentication, search]);
 
@@ -30,16 +31,8 @@ export const SignIn = () => {
           </CardDescription>
         </CardHeader>
         <CardContent>
-          <div className="flex flex-col gap-2 justify-center">
-            <Button
-              onClick={() => context.authentication?.signIn()}
-              variant="default"
-            >
-              Login
-            </Button>
-            <Button variant="link" className="text-muted-foreground" asChild>
-              <Link to="/">Go home</Link>
-            </Button>
+          <div className="flex items-center text-sm font-medium gap-2">
+            <Spinner /> Redirecting...
           </div>
         </CardContent>
       </Card>

package/src/lib/authentication/errors.ts

@@ -1,21 +1,35 @@
-export class AuthorizationError extends Error {}
+import type { OAuth2Error } from "oauth4webapi";
+import { ZudokuError, type ZudokuErrorOptions } from "../util/invariant.js";
 
-interface OAuthError {
-  readonly error: string;
-  readonly error_description?: string;
-  readonly error_uri?: string;
-  readonly algs?: string;
-  readonly scope?: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly [parameter: string]: any | undefined;
-}
+export class AuthorizationError extends Error {}
 
-export class OAuthAuthorizationError extends AuthorizationError {
+export class OAuthAuthorizationError extends ZudokuError {
   constructor(
     message: string,
-    public error: OAuthError,
-    options?: ErrorOptions,
+    public error: OAuth2Error,
+    options?: ZudokuErrorOptions,
   ) {
     super(message, options);
   }
 }
+
+export type OAuthErrorType =
+  // Authorization errors
+  | "invalid_request"
+  | "unauthorized_client"
+  | "access_denied"
+  | "unsupported_response_type"
+  | "invalid_scope"
+  | "server_error"
+  | "temporarily_unavailable"
+  // Token errors
+  | "invalid_client"
+  | "invalid_grant"
+  | "unsupported_grant_type"
+  // Custom errors
+  | "invalid_state"
+  | "missing_code_verifier"
+  | "network_error"
+  | "token_expired"
+  | "configuration_error"
+  | "unknown_error";

package/src/lib/authentication/hook.ts

@@ -1,6 +1,8 @@
 import { useZudoku } from "../components/context/ZudokuContext.js";
 import { useAuthState } from "./state.js";
 
+export type UseAuthReturn = ReturnType<typeof useAuth>;
+
 export const useAuth = () => {
   const { authentication } = useZudoku();
   const authState = useAuthState();

package/src/lib/authentication/providers/azureb2c.tsx

@@ -1,5 +1,6 @@
 import type { AuthenticationResult, EventMessage } from "@azure/msal-browser";
 import { EventType, PublicClientApplication } from "@azure/msal-browser";
+import { ErrorBoundary } from "react-error-boundary";
 import { type AzureB2CAuthenticationConfig } from "../../../config/config.js";
 import { ClientOnly } from "../../components/ClientOnly.js";
 import { joinUrl } from "../../util/joinUrl.js";
@@ -7,12 +8,12 @@ import {
   type AuthenticationPlugin,
   type AuthenticationProviderInitializer,
 } from "../authentication.js";
+import { CoreAuthenticationPlugin } from "../AuthenticationPlugin.js";
 import { CallbackHandler } from "../components/CallbackHandler.js";
+import { OAuthErrorPage } from "../components/OAuthErrorPage.js";
 import { AuthorizationError } from "../errors.js";
 import { useAuthState } from "../state.js";
 
-import { CoreAuthenticationPlugin } from "../AuthenticationPlugin.js";
-
 const AZUREB2C_CALLBACK_PATH = "/oauth/callback";
 
 export class AzureB2CAuthPlugin
@@ -181,7 +182,11 @@ export class AzureB2CAuthPlugin
         path: AZUREB2C_CALLBACK_PATH,
         element: (
           <ClientOnly>
-            <CallbackHandler handleCallback={this.handleCallback} />
+            <ErrorBoundary
+              fallbackRender={({ error }) => <OAuthErrorPage error={error} />}
+            >
+              <CallbackHandler handleCallback={this.handleCallback} />
+            </ErrorBoundary>
           </ClientOnly>
         ),
       },

package/src/lib/authentication/providers/clerk.tsx

@@ -15,6 +15,7 @@ const clerkAuth: AuthenticationProviderInitializer<
   ClerkAuthenticationConfig
 > = ({
   clerkPubKey,
+  jwtTemplateName,
   redirectToAfterSignOut = "/",
   redirectToAfterSignUp,
   redirectToAfterSignIn,
@@ -61,7 +62,9 @@ const clerkAuth: AuthenticationProviderInitializer<
     if (!clerkApi?.session) {
       throw new Error("No session available");
     }
-    const response = await clerkApi.session.getToken();
+    const response = await clerkApi.session.getToken({
+      template: jwtTemplateName,
+    });
     if (!response) {
       throw new Error("Could not get access token from Clerk");
     }