Address compliance-portal review feedback

Fix the valid issues raised in the scaffold review.

UI kit: the Button loading state now replaces only the leading icon
instead of dropping the label, Button consumes the `active` variant so
it no longer leaks onto the DOM, and every v2 skeleton sets aria-hidden
after the prop spread so a consumer cannot override it.

@probo/relay: guard the caller-supplied onCompleted/onError callbacks so
a throwing callback still settles the awaitable mutation promise instead
of leaving it pending.

compliance-portal: normalize external website hrefs and read hostname
via URL.hostname, add a localized catch-all not-found route, and widen
the .gitattributes glob so colocated __generated__ artifacts at any depth
are marked generated.

Docs: correct the forms guide (Base UI passes plain values, Zod v3
flatten API), spread the child fragment in the permissions example, and
drop references to v2 components that do not exist in the ui guide.

Signed-off-by: Émile Ré <emile@probo.com>

apps/compliance-portal/.gitattributes

@@ -1,2 +1 @@
-__generated__/*.graphql linguist-generated
-__generated__/*.js linguist-generated
+**/__generated__/** linguist-generated

apps/compliance-portal/src/_locales/en-US.json

@@ -28,5 +28,10 @@
   "requests": {
     "title": "Data Requests",
     "newRequest": "New Request"
+  },
+  "notFound": {
+    "title": "Page not found",
+    "description": "The page you are looking for does not exist or has moved.",
+    "backHome": "Back to home"
   }
 }

apps/compliance-portal/src/_locales/fr-FR.json

@@ -28,5 +28,10 @@
   "requests": {
     "title": "Demandes de données",
     "newRequest": "Nouvelle demande"
+  },
+  "notFound": {
+    "title": "Page introuvable",
+    "description": "La page que vous recherchez n'existe pas ou a été déplacée.",
+    "backHome": "Retour à l'accueil"
   }
 }

apps/compliance-portal/src/components/Hero/OrganizationContactInfo.tsx

@@ -16,7 +16,7 @@ import { EnvelopeIcon, GlobeSimpleIcon, MapPinSimpleIcon } from "@phosphor-icons
 import { Text } from "@probo/ui/src/v2/typography/Text";
 import { graphql, useFragment } from "react-relay";
 
-import { hostnameOf } from "#/lib/url/hostname";
+import { externalHref, hostnameOf } from "#/lib/url/hostname";
 
 import type { OrganizationContactInfo_organization$key } from "./__generated__/OrganizationContactInfo_organization.graphql";
 import { organizationContactInfo } from "./variants";
@@ -54,7 +54,7 @@ export function OrganizationContactInfo({ organizationKey }: OrganizationContact
       {hasWebsite && (
         <a
           className={link()}
-          href={organization.websiteUrl}
+          href={externalHref(organization.websiteUrl)}
           target="_blank"
           rel="noopener noreferrer"
         >

apps/compliance-portal/src/lib/url/hostname.ts

@@ -12,12 +12,25 @@
 // OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 // PERFORMANCE OF THIS SOFTWARE.
 
+// Prepend https:// when a URL carries no http(s) scheme, so a protocol-less
+// value (e.g. "blaxel.ai") parses as absolute instead of being treated as a
+// relative path.
+function withHttpScheme(url: string): string {
+  return /^https?:\/\//i.test(url) ? url : `https://${url}`;
+}
+
 // Show only the hostname for a URL (e.g. "https://blaxel.ai/x" -> "blaxel.ai"),
 // falling back to the raw value when it cannot be parsed.
 export function hostnameOf(url: string): string {
   try {
-    return new URL(url).host;
+    return new URL(withHttpScheme(url)).hostname;
   } catch {
     return url;
   }
 }
+
+// Build a safe absolute href for an external link, normalizing the scheme so a
+// protocol-less value does not resolve as a relative link.
+export function externalHref(url: string): string {
+  return withHttpScheme(url);
+}

apps/compliance-portal/src/pages/NotFoundPage.tsx

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Probo Inc <hello@probo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+import { Link } from "@probo/ui/src/v2/Button/Link";
+import { Heading } from "@probo/ui/src/v2/typography/Heading";
+import { Text } from "@probo/ui/src/v2/typography/Text";
+import { useTranslation } from "react-i18next";
+
+import { HeaderBand } from "#/components/HeaderBand/HeaderBand";
+
+// Catch-all page for portal paths that match no route, so an unknown URL renders
+// an explicit not-found state inside the layout instead of an empty body.
+export default function NotFoundPage() {
+  const { t } = useTranslation();
+
+  return (
+    <HeaderBand>
+      <div className="flex flex-col items-start gap-4">
+        <Heading level={1} size={7} weight="medium" highContrast>
+          {t("notFound.title")}
+        </Heading>
+        <Text size={2} color="neutral">
+          {t("notFound.description")}
+        </Text>
+        <Link to="/" variant="soft" color="neutral" highContrast size={2}>
+          {t("notFound.backHome")}
+        </Link>
+      </div>
+    </HeaderBand>
+  );
+}

apps/compliance-portal/src/routes.tsx

@@ -47,6 +47,10 @@ const routes = [
         path: "requests",
         Component: lazy(() => import("#/pages/RequestsPage")),
       },
+      {
+        path: "*",
+        Component: lazy(() => import("#/pages/NotFoundPage")),
+      },
     ],
   },
 ] satisfies AppRoute[];

contrib/claude/forms.md

@@ -93,10 +93,10 @@ export function CreateMeasureForm({ onValid }: CreateMeasureFormProps) {
     <Form
       errors={errors}
       onClearErrors={setErrors}
-      onFormSubmit={(formData) => {
-        const result = schema.safeParse(Object.fromEntries(formData));
+      onFormSubmit={(formValues) => {
+        const result = schema.safeParse(formValues);
         if (!result.success) {
-          setErrors(z.flattenError(result.error).fieldErrors);
+          setErrors(result.error.flatten().fieldErrors);
           return;
         }
         onValid(result.data);

contrib/claude/permissions.md

@@ -23,12 +23,15 @@ const documentListItemFragment = graphql`
     title
     canUpdate: permission(action: "core:document:update")
     canDelete: permission(action: "core:document:delete")
+    ...EditDocumentDialog_document
   }
 `;
 ```
 
 Colocate the permission with the action it gates — never drill a `canDelete` boolean down as a prop from a parent (the same data-as-props rule as everywhere else; see [`react-components.md`](react-components.md#props-are-for-configuration-and-composition-not-data)).
 
+Spread a child's fragment (`...EditDocumentDialog_document`) when you forward the node to that child as a fragment key. `useFragment` returns plain data, but Relay keeps the spread fragment refs on it, so the resolved `document` doubles as the key the child's own `useFragment` expects. Without the spread, `documentKey={document}` would hand the child masked data with no ref and fail at runtime (see [`relay.md`](relay.md)).
+
 ## Gate the action on the boolean
 
 Read the boolean via `useFragment` and gate the control. Default to **hiding** an action the user cannot perform; **disable** (with an explanatory tooltip) only when the action's *absence* would be confusing.

contrib/claude/ui.md

@@ -295,13 +295,13 @@ Components fall into two categories: **primitives** and **compound** components.
 
 ### Primitives
 
-**Primitives** (`Text`, `Image`, form inputs, layout helpers, `ListItem`) are self-contained — they render a single semantic element with their own styling. A primitive **is its own shell**: there is no separate shell wrapper. Each primitive has a paired skeleton (`TextSkeleton`, `ImageSkeleton`) that matches its dimensions.
+**Primitives** (`Text`, `Avatar`, `Badge`, form inputs, layout helpers) are self-contained — they render a single semantic element with their own styling. A primitive **is its own shell**: there is no separate shell wrapper. Each primitive has a paired skeleton (`TextSkeleton`, `AvatarSkeleton`) that matches its dimensions.
 
 ### Compound components
 
-**Compound components** (`ImageCard`, …) assemble multiple primitives into a larger region. When logic (state, effects, data) lives inside the top-level component, a **shell** separates layout from behavior:
+**Compound components** (`Card`, `Dropdown`, …) assemble multiple primitives into a larger region. When logic (state, effects, data) lives inside the top-level component, a **shell** separates layout from behavior:
 
-- **Shell** — pure layout frame that accepts region props (`image`, `text`, …) as `ReactNode` and applies `tv` slot classes. No state, no effects, no data.
+- **Shell** — pure layout frame that accepts region props (`media`, `text`, …) as `ReactNode` and applies `tv` slot classes. No state, no effects, no data.
 - **Root** — owns the logic and renders the shell, passing primitives into its region props.
 - **Skeleton** — reuses the **same shell** with skeleton primitives, so the loading placeholder is structurally identical without pulling in the logic graph.
 

packages/relay/src/useMutation.ts

@@ -81,11 +81,24 @@ export function createUseMutation(useNotifier: () => MutationNotifier) {
           );
         }
 
+        function toError(value: unknown): Error {
+          return value instanceof Error ? value : new Error(String(value));
+        }
+
         return new Promise<T["response"]>((resolve, reject) => {
           commit({
             ...config,
             onCompleted: (response, errors) => {
-              config.onCompleted?.(response, errors);
+              // A throwing caller callback must still settle the wrapper promise,
+              // otherwise `await mutate()` would hang forever.
+              try {
+                config.onCompleted?.(response, errors);
+              } catch (callbackError) {
+                const error = toError(callbackError);
+                notifyError(error);
+                reject(error);
+                return;
+              }
               if (errors && errors.length > 0) {
                 const [payloadError] = errors;
                 notifyError(payloadError);
@@ -102,7 +115,13 @@ export function createUseMutation(useNotifier: () => MutationNotifier) {
               resolve(response);
             },
             onError: (error) => {
-              config.onError?.(error);
+              // Swallow a throwing caller callback so the original mutation error
+              // still flows through to the notifier and the rejection.
+              try {
+                config.onError?.(error);
+              } catch {
+                // Intentionally ignored: the mutation error below is authoritative.
+              }
               notifyError(error);
               reject(error);
             },

packages/ui/src/v2/Avatar/AvatarSkeleton.tsx

@@ -24,5 +24,5 @@ export type AvatarSkeletonProps = Omit<ComponentProps<"span">, "children"> & Var
 export function AvatarSkeleton(props: AvatarSkeletonProps) {
   const { size, radius, className, ...rest } = props;
 
-  return <span aria-hidden className={avatarSkeleton({ size, radius, className })} {...rest} />;
+  return <span className={avatarSkeleton({ size, radius, className })} {...rest} aria-hidden />;
 }

packages/ui/src/v2/Badge/BadgeSkeleton.tsx

@@ -24,5 +24,5 @@ export type BadgeSkeletonProps = Omit<ComponentProps<"span">, "children"> & Vari
 export function BadgeSkeleton(props: BadgeSkeletonProps) {
   const { size, className, ...rest } = props;
 
-  return <span aria-hidden className={badgeSkeleton({ size, className })} {...rest} />;
+  return <span className={badgeSkeleton({ size, className })} {...rest} aria-hidden />;
 }

packages/ui/src/v2/Button/Button.tsx

@@ -32,7 +32,7 @@ export type ButtonProps
 // or router link (Link) are separate components. See contrib/claude/ui.md.
 export function Button(props: ButtonProps) {
   const {
-    size, variant, color, highContrast, className,
+    size, variant, color, highContrast, active, className,
     iconStart, iconEnd, loading = false, disabled, type = "button", children, ...rest
   } = props;
 
@@ -41,18 +41,12 @@ export function Button(props: ButtonProps) {
       type={type}
       disabled={disabled || loading}
       aria-busy={loading || undefined}
-      className={button({ size, variant, color, highContrast, className })}
+      className={button({ size, variant, color, highContrast, active, className })}
       {...rest}
     >
-      {loading
-        ? <SpinnerGapIcon className="animate-spin" aria-hidden />
-        : (
-            <>
-              {iconStart}
-              {children}
-              {iconEnd}
-            </>
-          )}
+      {loading ? <SpinnerGapIcon className="animate-spin" aria-hidden /> : iconStart}
+      {children}
+      {iconEnd}
     </button>
   );
 }

packages/ui/src/v2/Button/ButtonSkeleton.tsx

@@ -24,5 +24,5 @@ export type ButtonSkeletonProps = Omit<ComponentProps<"span">, "children"> & Var
 export function ButtonSkeleton(props: ButtonSkeletonProps) {
   const { size, className, ...rest } = props;
 
-  return <span aria-hidden className={buttonSkeleton({ size, className })} {...rest} />;
+  return <span className={buttonSkeleton({ size, className })} {...rest} aria-hidden />;
 }

packages/ui/src/v2/Callout/CalloutSkeleton.tsx

@@ -23,5 +23,5 @@ export type CalloutSkeletonProps = Omit<ComponentProps<"div">, "children"> & Var
 export function CalloutSkeleton(props: CalloutSkeletonProps) {
   const { size, className, ...rest } = props;
 
-  return <div aria-hidden className={calloutSkeleton({ size, className })} {...rest} />;
+  return <div className={calloutSkeleton({ size, className })} {...rest} aria-hidden />;
 }

packages/ui/src/v2/Card/CardSkeleton.tsx

@@ -23,5 +23,5 @@ export type CardSkeletonProps = Omit<ComponentProps<"div">, "children"> & Varian
 export function CardSkeleton(props: CardSkeletonProps) {
   const { size, className, ...rest } = props;
 
-  return <div aria-hidden className={cardSkeleton({ size, className })} {...rest} />;
+  return <div className={cardSkeleton({ size, className })} {...rest} aria-hidden />;
 }

packages/ui/src/v2/IconButton/IconButtonSkeleton.tsx

@@ -24,5 +24,5 @@ export type IconButtonSkeletonProps = Omit<ComponentProps<"span">, "children"> &
 export function IconButtonSkeleton(props: IconButtonSkeletonProps) {
   const { size, className, ...rest } = props;
 
-  return <span aria-hidden className={iconButtonSkeleton({ size, className })} {...rest} />;
+  return <span className={iconButtonSkeleton({ size, className })} {...rest} aria-hidden />;
 }

packages/ui/src/v2/typography/HeadingSkeleton.tsx

@@ -26,7 +26,7 @@ export function HeadingSkeleton(props: HeadingSkeletonProps) {
   const { size, className, ...rest } = props;
 
   return (
-    <span aria-hidden className={headingSkeleton({ size, className })} {...rest}>
+    <span className={headingSkeleton({ size, className })} {...rest} aria-hidden>
       {"\u00A0"}
     </span>
   );

packages/ui/src/v2/typography/TextSkeleton.tsx

@@ -26,7 +26,7 @@ export function TextSkeleton(props: TextSkeletonProps) {
   const { size, className, ...rest } = props;
 
   return (
-    <span aria-hidden className={textSkeleton({ size, className })} {...rest}>
+    <span className={textSkeleton({ size, className })} {...rest} aria-hidden>
       {"\u00A0"}
     </span>
   );