chore(autonomous-session): consolidate uncommitted work from prior session

Bundles the prior autonomous-session output that was sitting unstaged:

- Em-dash sweep across src/ + tests/ (en-dash/em-dash to hyphen, ~2280 instances)
- country-flag-icons rollout (CountryFlag component, replaces emoji glyphs that
  never rendered on Windows; lazy-loads the 3x2 SVG index as a single chunk
  after the per-subpath dynamic-import approach silently failed in webpack)
- Admin IA Phase 1+2: 7-domain regroup, 41 to 38 pages, /admin/berths index,
  redirects (ocr to ai, reports to dashboard, invitations to users),
  docs/admin-ia-proposal.md
- Per-template email tester (registry + endpoint + UI on Email admin page)
- Cancel-document mode picker (delete-from-Documenso vs keep-for-audit)
- Dashboard PDF report: 25 widgets, SVG charts, date-range picker, 11 resolvers
- Customize-widgets per-region sortables at xl+ (charts/rails/feed); single
  flat sortable below xl when the layout stacks; per-viewport saved orders
- Audit doc updates capturing each shipped item
- Lint fixes: react-compiler immutability in DonutChart (reduce instead of
  let-reassign), set-state-in-effect disables in CountryFlag and
  UploadForSigning preview-bytes effect, unused 'confirm' destructures in
  interest contract + reservation tabs, unescaped apostrophe in test-template
  card copy

src/hooks/use-dashboard-widgets.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useMemo } from 'react';
+import { useMemo, useSyncExternalStore } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 
 import { apiFetch } from '@/lib/api/client';
@@ -11,30 +11,55 @@ interface PreferencesResponse {
   data?: {
     dashboardWidgets?: Record<string, boolean>;
     /**
-     * Ordered widget ids. When present, the visible-widgets list is
-     * sorted by this order first; unlisted widgets fall through to the
-     * registry's declared order. Per group only — the dashboard shell
-     * groups by widget.group (chart / rail / feed) before sorting.
+     * Ordered widget ids for the desktop (xl, >= 1280px) split layout.
+     * When present, visible widgets are sorted by this order first;
+     * unlisted widgets fall through to the registry's declared order.
      */
     dashboardWidgetOrder?: string[];
+    /**
+     * Ordered widget ids for the stacked layout (< 1280px). Falls back
+     * to `dashboardWidgetOrder` then registry order when unset.
+     */
+    dashboardWidgetOrderMobile?: string[];
     // Other fields exist (timezone, locale, …) but we don't need them
-    // here — the typed access is intentionally narrow.
+    // here - the typed access is intentionally narrow.
   };
 }
 
 interface UseDashboardWidgetsOptions {
   /** SSR-prefetched visibility map. When provided, seeds the react-query
-   *  cache so the first render uses the rep's saved layout — no reflow when
+   *  cache so the first render uses the rep's saved layout - no reflow when
    *  the client fetch resolves. Pass `null` (not `undefined`) when the
    *  caller has confirmed there is no stored preference so we don't keep
    *  showing the loading layout. */
   initialVisibility?: Record<string, boolean> | null;
 }
 
+// xl breakpoint matches Tailwind's `xl:` modifier and the dashboard
+// shell's actual layout-flip point (charts | rails side-by-side at
+// >= 1280, stacked below). Reading from `useSyncExternalStore` keeps
+// renders pure so the React Compiler can lift the call.
+const XL_QUERY = '(min-width: 1280px)';
+function subscribeXl(callback: () => void): () => void {
+  if (typeof window === 'undefined') return () => {};
+  const mq = window.matchMedia(XL_QUERY);
+  mq.addEventListener('change', callback);
+  return () => mq.removeEventListener('change', callback);
+}
+function getXlSnapshot(): boolean {
+  return window.matchMedia(XL_QUERY).matches;
+}
+function getXlServerSnapshot(): boolean {
+  return true;
+}
+function useIsXlLayout(): boolean {
+  return useSyncExternalStore(subscribeXl, getXlSnapshot, getXlServerSnapshot);
+}
+
 /**
  * Returns the dashboard widget list filtered by the user's visibility
  * preferences and exposes a toggle. Single source of truth for "what's
- * showing on the dashboard right now" — used by both `DashboardShell`
+ * showing on the dashboard right now" - used by both `DashboardShell`
  * and the settings UI.
  *
  * Stored shape: `preferences.dashboardWidgets: { [widgetId]: boolean }`.
@@ -44,6 +69,7 @@ interface UseDashboardWidgetsOptions {
 export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
   const queryClient = useQueryClient();
   const integrations = useDashboardIntegrations();
+  const isXl = useIsXlLayout();
 
   const { data, isLoading } = useQuery<PreferencesResponse>({
     queryKey: ['me', 'preferences', 'dashboard-widgets'],
@@ -60,7 +86,7 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
   // (i.e. its required integration is connected). The picker iterates
   // this list, and the visible-widgets render path filters off the same
   // list so flipping on a widget whose service isn't wired up does
-  // nothing silently — the toggle simply isn't shown.
+  // nothing silently - the toggle simply isn't shown.
   const availableWidgets: DashboardWidget[] = useMemo(
     () => DASHBOARD_WIDGETS.filter((w) => !w.requires || integrations.available[w.requires]),
     [integrations],
@@ -77,14 +103,20 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
 
   // Order map: widgetId → rank. Unlisted widgets get +Infinity so they
   // fall after the explicitly-ordered ones in stable registry order.
+  // The active list is the viewport-matched one; the stacked layout
+  // (< xl) falls back to the desktop order when the rep hasn't yet
+  // customized mobile, so a partially-configured user sees consistent
+  // ordering across devices instead of an unstyled jumble.
   const orderRank: Record<string, number> = useMemo(() => {
-    const order = data?.data?.dashboardWidgetOrder ?? [];
+    const desktopOrder = data?.data?.dashboardWidgetOrder ?? [];
+    const mobileOrder = data?.data?.dashboardWidgetOrderMobile;
+    const order = isXl ? desktopOrder : (mobileOrder ?? desktopOrder);
     const map: Record<string, number> = {};
     order.forEach((id, idx) => {
       map[id] = idx;
     });
     return map;
-  }, [data]);
+  }, [data, isXl]);
 
   const visibleWidgets: DashboardWidget[] = useMemo(() => {
     const visible = availableWidgets.filter((w) => visibility[w.id]);
@@ -147,7 +179,7 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
 
   /**
    * Restores each widget's visibility to its registry `defaultVisible`.
-   * Different from `setAll(true)` — it keeps the "off by default" widgets
+   * Different from `setAll(true)` - it keeps the "off by default" widgets
    * (KPI tiles, Berth Status donut, Source Conversion, Hot Deals) off so
    * reps end up with the original out-of-the-box dashboard. Scoped to
    * `availableWidgets` so disconnected integrations don't sneak in.
@@ -160,13 +192,24 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
 
   // Persist the order list. Optimistic so the dashboard reflows on
   // drop; the PATCH races behind. Falls back to invalidating on error.
+  // The mutation accepts a `{ scope }` so it writes to the right field
+  // (xl → dashboardWidgetOrder, stacked → dashboardWidgetOrderMobile).
   const orderMutation = useMutation({
-    mutationFn: async (nextOrder: string[]) =>
+    mutationFn: async ({
+      nextOrder,
+      scope,
+    }: {
+      nextOrder: string[];
+      scope: 'desktop' | 'mobile';
+    }) =>
       apiFetch<PreferencesResponse>('/api/v1/users/me/preferences', {
         method: 'PATCH',
-        body: { dashboardWidgetOrder: nextOrder },
+        body:
+          scope === 'desktop'
+            ? { dashboardWidgetOrder: nextOrder }
+            : { dashboardWidgetOrderMobile: nextOrder },
       }),
-    onMutate: async (nextOrder) => {
+    onMutate: async ({ nextOrder, scope }) => {
       await queryClient.cancelQueries({ queryKey: ['me', 'preferences', 'dashboard-widgets'] });
       const previous = queryClient.getQueryData<PreferencesResponse>([
         'me',
@@ -176,7 +219,12 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
       queryClient.setQueryData<PreferencesResponse>(
         ['me', 'preferences', 'dashboard-widgets'],
         (old) => ({
-          data: { ...(old?.data ?? {}), dashboardWidgetOrder: nextOrder },
+          data: {
+            ...(old?.data ?? {}),
+            ...(scope === 'desktop'
+              ? { dashboardWidgetOrder: nextOrder }
+              : { dashboardWidgetOrderMobile: nextOrder }),
+          },
         }),
       );
       return { previous };
@@ -191,8 +239,14 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
     },
   });
 
+  /**
+   * Persist a new visible-widget order to the field that matches the
+   * current viewport - desktop (xl+) gets one order, the stacked layout
+   * gets its own. The hook decides the scope based on `useIsXlLayout()`
+   * so callers (the modal) don't need to repeat the breakpoint logic.
+   */
   function setOrder(nextOrder: string[]) {
-    orderMutation.mutate(nextOrder);
+    orderMutation.mutate({ nextOrder, scope: isXl ? 'desktop' : 'mobile' });
   }
 
   return {
@@ -200,12 +254,16 @@ export function useDashboardWidgets(options: UseDashboardWidgetsOptions = {}) {
     /**
      * Widgets that can render right now (registry minus those whose
      * required integration isn't connected). Use this for the picker
-     * AND for the dashboard render — both surfaces stay in sync.
+     * AND for the dashboard render - both surfaces stay in sync.
      */
     allWidgets: availableWidgets,
-    /** Visible widgets, sorted by the rep's `dashboardWidgetOrder` then
-     *  by registry index. */
+    /** Visible widgets, sorted by the rep's order for the active
+     *  layout tier (desktop vs stacked) then by registry index. */
     visibleWidgets,
+    /** True when the dashboard's xl two-column layout is active. Lets
+     *  callers (the customize modal) tailor copy and split into region-
+     *  scoped sortables vs a single flat list. */
+    isXlLayout: isXl,
     /** Map of widgetId → visible. Use for switch state binding. */
     visibility,
     /** Current rank per widget id (for SortableContext keying). */