zudoku 0.0.0-fd0986c → 0.0.0-fdf886de

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,30 @@
     @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::after {
+    @apply absolute left-0 top-0 bottom-0 right-auto translate-x-full content-[''];
+    border-left: 3px solid
+      hsl(from var(--highlighted-bg) h s calc(l + 4 * var(--dark)));
   }
 
   .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

@@ -1,4 +1,4 @@
-import { type RouteObject } from "react-router";
+import type { RouteObject } from "react-router";
 import { configuredApiKeysPlugin } from "virtual:zudoku-api-keys-plugin";
 import {
   configuredApiCatalogPlugins,
@@ -15,11 +15,13 @@ import "virtual:zudoku-theme.css";
 import {
   BuildCheck,
   Layout,
+  Meta,
   RouteGuard,
   RouterError,
   StatusPage,
-  Zudoku,
-} from "zudoku/components";
+} from "zudoku/__internal";
+import { Zudoku } from "zudoku/components";
+import { Outlet } from "zudoku/router";
 import type { ZudokuConfig } from "../config/config.js";
 import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
 import { isNavigationPlugin } from "../lib/core/plugins.js";
@@ -107,23 +109,33 @@ export const getRoutesByConfig = (config: ZudokuConfig): RouteObject[] => {
       element: (
         <Zudoku {...options}>
           <BuildCheck
-            buildId={
-              import.meta.env.IS_ZUPLO && import.meta.env.ZUPLO_BUILD_ID
-                ? import.meta.env.ZUPLO_BUILD_ID
-                : undefined
-            }
+            buildId={import.meta.env.ZUPLO_BUILD_ID}
+            environmentType={import.meta.env.ZUPLO_ENVIRONMENT_TYPE}
           />
-          <Layout />
+          <Outlet />
         </Zudoku>
       ),
       hydrateFallbackElement: <div>Loading...</div>,
       children: [
         {
-          element: <RouteGuard />,
+          element: (
+            <Meta>
+              <RouteGuard />
+            </Meta>
+          ),
           errorElement: <RouterError />,
-          children: routes,
+          children: routes.map((r) =>
+            r.handle?.layout === "none" ? r : wrapWithLayout(r),
+          ),
         },
       ],
     },
   ];
 };
+
+const wrapWithLayout = (route: RouteObject) => {
+  return {
+    element: <Layout />,
+    children: [route],
+  };
+};

package/src/app/standalone.tsx

@@ -1,6 +1,6 @@
 import { createRoot } from "react-dom/client";
 import { createBrowserRouter } from "react-router";
-import { Bootstrap } from "zudoku/components";
+import { Bootstrap } from "zudoku/__internal";
 import type { ZudokuConfig } from "../config/validators/validate.js";
 import { openApiPlugin } from "../lib/plugins/openapi/index.js";
 import "../lib/util/logInit.js";

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

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

@@ -1,5 +1,6 @@
 import logger from "loglevel";
 import * as oauth from "oauth4webapi";
+import { ErrorBoundary } from "react-error-boundary";
 import { type OpenIDAuthenticationConfig } from "../../../config/config.js";
 import { ClientOnly } from "../../components/ClientOnly.js";
 import { joinUrl } from "../../util/joinUrl.js";
@@ -9,6 +10,7 @@ import {
 } from "../authentication.js";
 import { CoreAuthenticationPlugin } from "../AuthenticationPlugin.js";
 import { CallbackHandler } from "../components/CallbackHandler.js";
+import { OAuthErrorPage } from "../components/OAuthErrorPage.js";
 import { AuthorizationError, OAuthAuthorizationError } from "../errors.js";
 import { useAuthState, type UserProfile } from "../state.js";
 
@@ -442,7 +444,11 @@ export class OpenIDAuthenticationProvider
         path: OPENID_CALLBACK_PATH,
         element: (
           <ClientOnly>
-            <CallbackHandler handleCallback={this.handleCallback} />
+            <ErrorBoundary
+              fallbackRender={({ error }) => <OAuthErrorPage error={error} />}
+            >
+              <CallbackHandler handleCallback={this.handleCallback} />
+            </ErrorBoundary>
           </ClientOnly>
         ),
       },

package/src/lib/components/BuildCheck.tsx

@@ -1,5 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { CircleFadingArrowUpIcon, LoaderCircleIcon } from "lucide-react";
+import { useEffect } from "react";
 import { z } from "zod/v4";
 import { Button } from "../ui/Button.js";
 
@@ -11,17 +12,17 @@ const BuildStatusSchema = z.object({
 
 export const BuildCheck = ({
   buildId,
+  environmentType,
   endpoint = "/__zuplo/docs",
 }: {
   buildId?: string;
+  environmentType?: string;
   endpoint?: string;
 }) => {
   const buildStatusQuery = useQuery({
     queryKey: ["zuplo-build-check", buildId, endpoint],
     refetchInterval: 3000,
-    enabled:
-      typeof buildId !== "undefined" &&
-      import.meta.env.ZUPLO_ENVIRONMENT_TYPE === "WORKING_COPY",
+    enabled: buildId !== undefined && environmentType === "WORKING_COPY",
     retry: false,
     queryFn: () =>
       fetch(endpoint, { signal: AbortSignal.timeout(2000) })
@@ -32,6 +33,15 @@ export const BuildCheck = ({
         .then((data) => BuildStatusSchema.parse(data)),
   });
 
+  useEffect(() => {
+    if (
+      buildStatusQuery.data?.status === "success" &&
+      buildStatusQuery.data.buildId
+    ) {
+      document.cookie = `zuplo-build=${buildStatusQuery.data.buildId}; path=/; max-age=300; secure; SameSite=None`;
+    }
+  }, [buildStatusQuery.data]);
+
   if (
     buildStatusQuery.isError ||
     !buildStatusQuery.data ||

package/src/lib/components/Header.tsx

@@ -90,9 +90,9 @@ export const Header = memo(function HeaderInner() {
         <PageProgress />
         <div className="max-w-screen-2xl mx-auto flex items-center justify-between h-(--top-header-height) px-4 lg:px-8 border-transparent">
           <div className="flex">
-            <Link to="/">
+            <Link to={site?.logo?.href ?? "/"}>
               <div className="flex items-center gap-3.5">
-                {site?.logo && (
+                {site?.logo ? (
                   <>
                     <img
                       src={logoLightSrc}
@@ -109,8 +109,9 @@ export const Header = memo(function HeaderInner() {
                       loading="lazy"
                     />
                   </>
+                ) : (
+                  <span className="font-semibold text-2xl">{site?.title}</span>
                 )}
-                <span className="font-semibold text-2xl">{site?.title}</span>
               </div>
             </Link>
           </div>

package/src/lib/components/Heading.tsx

@@ -66,7 +66,7 @@ export const Heading = ({
   return (
     <Component
       className={heading({
-        className: cn(className, "flex items-center gap-[0.33em]"),
+        className: cn("flex items-center gap-[0.33em]", className),
         level,
       })}
       ref={registerNavigationAnchor ? ref : undefined}

package/src/lib/components/Layout.tsx

@@ -1,8 +1,6 @@
-import { Helmet } from "@zudoku/react-helmet-async";
 import { Suspense, useEffect, type ReactNode } from "react";
-import { Outlet, useLocation } from "react-router";
+import { Outlet } from "react-router";
 import { cn } from "../util/cn.js";
-import { joinUrl } from "../util/joinUrl.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useZudoku } from "./context/ZudokuContext.js";
@@ -19,8 +17,7 @@ const LoadingFallback = () => (
 );
 
 export const Layout = ({ children }: { children?: ReactNode }) => {
-  const { meta, authentication, options } = useZudoku();
-  const location = useLocation();
+  const { authentication } = useZudoku();
 
   useScrollToAnchor();
   useScrollToTop();
@@ -32,22 +29,6 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
 
   return (
     <>
-      <Helmet titleTemplate={meta?.title}>
-        {options.canonicalUrlOrigin && (
-          <link
-            rel="canonical"
-            href={joinUrl(
-              options.canonicalUrlOrigin,
-              options.basePath,
-              location.pathname,
-            )}
-          />
-        )}
-        {meta?.description && (
-          <meta name="description" content={meta.description} />
-        )}
-        {meta?.favicon && <link rel="icon" href={meta.favicon} />}
-      </Helmet>
       <Slot.Target name="layout-before-head" />
       <Header />
       <Slot.Target name="layout-after-head" />

package/src/lib/components/Markdown.tsx

@@ -1,5 +1,5 @@
 import { memo, useMemo } from "react";
-import { MarkdownHooks, type Components } from "react-markdown";
+import ReactMarkdown, { type Components } from "react-markdown";
 import rehypeRaw from "rehype-raw";
 import remarkGfm from "remark-gfm";
 import { createConfiguredShikiRehypePlugins } from "../shiki.js";
@@ -35,13 +35,13 @@ export const Markdown = memo(
 
     return (
       <Typography className={className}>
-        <MarkdownHooks
+        <ReactMarkdown
           remarkPlugins={remarkPlugins}
           rehypePlugins={rehypePlugins}
           components={mdComponents}
         >
           {content}
-        </MarkdownHooks>
+        </ReactMarkdown>
       </Typography>
     );
   },

package/src/lib/components/Meta.tsx

@@ -0,0 +1,32 @@
+import { Helmet } from "@zudoku/react-helmet-async";
+import type { PropsWithChildren } from "react";
+import { useLocation } from "react-router";
+import { joinUrl } from "../util/joinUrl.js";
+import { useZudoku } from "./context/ZudokuContext.js";
+
+export const Meta = ({ children }: PropsWithChildren) => {
+  const { meta, options } = useZudoku();
+  const location = useLocation();
+
+  return (
+    <>
+      <Helmet titleTemplate={meta?.title} defaultTitle={meta?.defaultTitle}>
+        {options.canonicalUrlOrigin && (
+          <link
+            rel="canonical"
+            href={joinUrl(
+              options.canonicalUrlOrigin,
+              options.basePath,
+              location.pathname,
+            )}
+          />
+        )}
+        {meta?.description && (
+          <meta name="description" content={meta.description} />
+        )}
+        {meta?.favicon && <link rel="icon" href={meta.favicon} />}
+      </Helmet>
+      {children}
+    </>
+  );
+};