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-breadcrumb-hint.ts

@@ -24,7 +24,7 @@ export function useBreadcrumbHint(hint: BreadcrumbHint | null | undefined): void
   const setHint = useBreadcrumbStore((s) => s.setHint);
   const clearHint = useBreadcrumbStore((s) => s.clearHint);
 
-  // Stringify for stable equality — caller can pass an object literal
+  // Stringify for stable equality - caller can pass an object literal
   // each render without wrecking effect deps. The serialized form is
   // tiny (handful of strings) so this is cheap.
   const serialized = hint ? JSON.stringify(hint) : null;

src/hooks/use-confirmation.tsx

@@ -26,7 +26,7 @@ interface ConfirmOptions {
 }
 
 /**
- * Programmatic, awaitable confirmation dialog — the imperative counterpart
+ * Programmatic, awaitable confirmation dialog - the imperative counterpart
  * to `<ConfirmationDialog>` (which needs a trigger element).
  *
  * Replaces the native `window.confirm()` pattern in 17 destructive flows
@@ -52,7 +52,7 @@ interface ConfirmOptions {
  *
  * The dialog renders into the component's tree once, and `confirm()`
  * resolves with the user's choice. Multiple sequential `confirm()`
- * calls are safe — each gets its own promise.
+ * calls are safe - each gets its own promise.
  */
 export function useConfirmation() {
   const [state, setState] = useState<(ConfirmOptions & { open: boolean }) | null>(null);

src/hooks/use-create-from-url.ts

@@ -6,7 +6,7 @@ import { useRouter, useSearchParams } from 'next/navigation';
 /**
  * Auto-opens a list page's create sheet when the URL carries `?create=1`,
  * then strips the param so a refresh / back-nav doesn't re-open it. Used
- * by the topbar's "+ New" dropdown — each menu item navigates to the
+ * by the topbar's "+ New" dropdown - each menu item navigates to the
  * relevant list page with `?create=1` so the user lands on the right
  * scoped view AND gets the create sheet popped in one click.
  */

src/hooks/use-dashboard-integrations.ts

@@ -6,12 +6,12 @@ import type { WidgetIntegration } from '@/components/dashboard/widget-registry';
 /**
  * Returns availability for each external integration a dashboard widget
  * might depend on. Lets the widget picker hide options whose underlying
- * service isn't wired up — so reps don't enable widgets that'd render
+ * service isn't wired up - so reps don't enable widgets that'd render
  * nothing.
  *
  * Add a new integration by:
  *   1. Extending `WidgetIntegration` in the registry.
- *   2. Probing the service here (cheap query is fine — the hook already
+ *   2. Probing the service here (cheap query is fine - the hook already
  *      ships its own network call so adding another doesn't change the
  *      cost model).
  *   3. Returning the boolean in the map.
@@ -24,13 +24,13 @@ export function useDashboardIntegrations(): {
   available: Record<WidgetIntegration, boolean>;
 } {
   const umami = useUmamiActive('today');
-  // Same probe the sidebar uses — `notConfigured: true` is the explicit
+  // Same probe the sidebar uses - `notConfigured: true` is the explicit
   // signal the server returns when the integration isn't wired up.
   const umamiAvailable = umami.isLoading
     ? true
     : (umami.data as { notConfigured?: boolean } | undefined)?.notConfigured !== true;
 
-  // Documenso has no dashboard widgets yet — wire a real probe when the
+  // Documenso has no dashboard widgets yet - wire a real probe when the
   // first one lands. Assuming available for now keeps the map honest if
   // a Documenso widget is added before this hook is updated.
   const documensoAvailable = true;

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). */

src/hooks/use-form-scroll-to-error.ts

@@ -4,7 +4,7 @@ import { useCallback } from 'react';
 import type { FieldErrors, FieldValues } from 'react-hook-form';
 
 // react-hook-form's handleSubmit is generic across the input vs.
-// transformed types. We don't need the strictness here — the wrapper
+// transformed types. We don't need the strictness here - the wrapper
 // just passes its handler through to whatever handleSubmit the caller
 // gave us. Use a loose type so 2-arg and 3-arg useForm() both work.
 type AnyHandleSubmit = (
@@ -15,7 +15,7 @@ type AnyHandleSubmit = (
 ) => (e?: React.BaseSyntheticEvent) => Promise<void>;
 
 /**
- * Find the nearest scrolling ancestor of a node — accounts for the
+ * Find the nearest scrolling ancestor of a node - accounts for the
  * common case of forms rendered inside a Sheet / Dialog body that owns
  * its own overflow-y. Falls back to `window` when no ancestor scrolls.
  */
@@ -35,7 +35,7 @@ function findScrollContainer(el: HTMLElement | null): HTMLElement | null {
 /**
  * Wrap react-hook-form's `handleSubmit` so validation failures scroll
  * the first errored field into view and focus it. Critical on tall
- * drawers / dialogs where the failing field is below the fold —
+ * drawers / dialogs where the failing field is below the fold -
  * without this the user is dropped at the top of the form with no
  * indication of what failed.
  *
@@ -58,7 +58,7 @@ export function useFormScrollToError<TFieldValues extends FieldValues>(
     (onValid: (data: any) => void | Promise<void>) => {
       return handleSubmit(onValid, () => {
         // react-hook-form calls this on validation failure. We already
-        // have `errors` from formState — read the first key and scroll
+        // have `errors` from formState - read the first key and scroll
         // its DOM node into view.
         const firstName = Object.keys(errors)[0];
         if (!firstName) return;

src/hooks/use-is-mobile.ts

@@ -9,7 +9,7 @@ import { useSyncExternalStore } from 'react';
 //
 // Previously the app used a binary `(max-width: 1023.98px)` split, which
 // rendered the mobile shell on iPad portrait AND on a half-screen 13"
-// Mac browser — neither is really "mobile." The tablet tier fills that
+// Mac browser - neither is really "mobile." The tablet tier fills that
 // gap so the desktop shell can render with a hidden-but-accessible
 // sidebar at those widths.
 
@@ -36,7 +36,7 @@ function getTierSnapshot(): ViewportTier {
 }
 
 function getTierServerSnapshot(): ViewportTier {
-  // Server has no window — default to desktop so the desktop shell
+  // Server has no window - default to desktop so the desktop shell
   // mounts on first paint. Client re-evaluates immediately on hydration
   // (useSyncExternalStore is server-mismatch-safe).
   return 'desktop';

src/hooks/use-paginated-query.ts

@@ -111,7 +111,7 @@ export function usePaginatedQuery<T>({
 
   /**
    * Atomically replace the entire filter set. Used by the saved-views
-   * apply path — calling `clearFilters()` + N x `setFilter()` in a row
+   * apply path - calling `clearFilters()` + N x `setFilter()` in a row
    * lost all but the last setFilter because each one reads the stale
    * `filters` closure and overwrites with `{...filters, key: val}`.
    * setAllFilters writes the whole object in one setState so the view

src/hooks/use-search.ts

@@ -5,7 +5,7 @@ import { keepPreviousData, useQuery } from '@tanstack/react-query';
 import { apiFetch } from '@/lib/api/client';
 import { useDebounce } from '@/hooks/use-debounce';
 
-// ─── Types — mirror SearchResults from search.service.ts ─────────────────────
+// ─── Types - mirror SearchResults from search.service.ts ─────────────────────
 
 export type BucketType =
   | 'clients'
@@ -243,7 +243,7 @@ export function useSearch(query: string, opts: UseSearchOptions = {}) {
       apiFetch<SearchResults>(`/api/v1/search?${params.toString()}`, { signal }),
     enabled,
     // Keep previous results visible while the next debounced query loads
-    // — eliminates the dropdown flicker when the user is typing fast.
+    // - eliminates the dropdown flicker when the user is typing fast.
     placeholderData: keepPreviousData,
     staleTime: 30_000,
   });
@@ -284,6 +284,6 @@ export async function trackEntityView(type: string, id: string): Promise<void> {
       body: { type, id },
     });
   } catch {
-    // Tracking is non-critical — never bubble up to the user.
+    // Tracking is non-critical - never bubble up to the user.
   }
 }

src/hooks/use-table-preferences.ts

@@ -26,7 +26,7 @@ interface MeResponse {
  * `defaultHidden` applies ONLY when the user has never saved a
  * preference for this entity (the stored entry is `undefined`). Once
  * the user explicitly toggles any column, their saved list takes over
- * — including the case where they've intentionally cleared it to an
+ * - including the case where they've intentionally cleared it to an
  * empty array (which means "show everything", overriding defaults).
  */
 export function useTablePreferences(entityType: string, defaultHidden: string[] = []) {
@@ -87,7 +87,7 @@ export function useTablePreferences(entityType: string, defaultHidden: string[]
           method: 'PATCH',
           body: { preferences: { tablePreferences: updated } },
         }).catch(() => {
-          // Network failures are non-fatal — the local UI keeps the
+          // Network failures are non-fatal - the local UI keeps the
           // chosen visibility for the rest of the session.
         });
       }, 600);
@@ -131,7 +131,7 @@ export function useTablePreferences(entityType: string, defaultHidden: string[]
   // Resolution order: local optimistic → remote saved → caller defaults.
   // The `remoteHidden ?? defaultHidden` step is what gives us the "hide
   // latestStage for fresh users, but respect their override once they
-  // touch it" behavior — saved value (even []) wins, defaults only fill
+  // touch it" behavior - saved value (even []) wins, defaults only fill
   // the never-saved case.
   const resolved = localHidden ?? remoteHidden ?? defaultHidden;
   const density: 'comfortable' | 'compact' = localDensity ?? remoteDensity ?? 'comfortable';

src/hooks/use-track-entity-view.ts

@@ -14,7 +14,7 @@ import { trackEntityView } from '@/hooks/use-search';
  * After the track POST resolves, invalidates the recently-viewed query
  * so the search dropdown re-fetches the freshly-updated list. Without
  * this, the overlay's query cache (mounted once at the layout root)
- * stays frozen on whatever it had at first paint — typically empty —
+ * stays frozen on whatever it had at first paint - typically empty -
  * and the user never sees the entity they just opened.
  */
 export function useTrackEntityView(

src/hooks/use-vocabulary.ts

@@ -12,7 +12,7 @@ interface VocabulariesResponse {
 /**
  * Fetches the effective per-port vocabulary list for a key. Falls back
  * to the shipped defaults when the request hasn't resolved or the key
- * is missing from the response. Cached for 5 minutes — vocabularies
+ * is missing from the response. Cached for 5 minutes - vocabularies
  * change rarely and the admin Vocabularies page invalidates by save.
  */
 export function useVocabulary(key: VocabularyKey): readonly string[] {

src/hooks/use-voice-transcription.ts

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
 /**
- * Web Speech API wrapper. Browser-only — gracefully reports `supported: false`
+ * Web Speech API wrapper. Browser-only - gracefully reports `supported: false`
  * when SpeechRecognition isn't available (Firefox, Safari < 14.1, server-side
  * render).
  *
@@ -16,7 +16,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
  *
  * The summary form appends `transcript` (final committed text) to the textarea
  * and separately persists it to `voiceTranscript` on the server. The rep can
- * still edit the summary freely — the raw transcript stays untouched.
+ * still edit the summary freely - the raw transcript stays untouched.
  */
 interface SpeechRecognitionEventLike {
   resultIndex: number;
@@ -69,7 +69,7 @@ export function useVoiceTranscription(opts?: { lang?: string }): VoiceTranscript
   // SSR-safe: getSpeechRecognitionCtor() returns null on the server. We want
   // the support flag to be stable across renders rather than flipping inside
   // an effect (set-state-in-effect lint), so derive it from the constructor
-  // lookup at render time — useState's lazy initializer runs once per mount.
+  // lookup at render time - useState's lazy initializer runs once per mount.
   const [supported] = useState(() => getSpeechRecognitionCtor() !== null);
   const [isListening, setIsListening] = useState(false);
   const [transcript, setTranscript] = useState('');
@@ -117,7 +117,7 @@ export function useVoiceTranscription(opts?: { lang?: string }): VoiceTranscript
       try {
         recognition.abort();
       } catch {
-        // ignore — already-stopped recognizers throw on abort()
+        // ignore - already-stopped recognizers throw on abort()
       }
       recognitionRef.current = null;
     };