@carlonicora/nextjs-jsonapi 1.133.0 → 1.134.0

package/src/components/containers/PageContainer.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useHeaderChildren } from "../../contexts/HeaderChildrenContext";
+import { useHeaderChildren, useHeaderMobileChildren } from "../../contexts/HeaderChildrenContext";
 import { useHeaderLeftContent } from "../../contexts/HeaderLeftContentContext";
+import { useHeaderLogo } from "../../contexts/HeaderLogoContext";
 import { cn } from "../../utils";
 import { Header } from "../navigations";
 
@@ -9,11 +10,15 @@ type PageContainerProps = { children: React.ReactNode; testId?: string; classNam
 
 export function PageContainer({ children, testId, className }: PageContainerProps) {
   const headerChildren = useHeaderChildren();
+  const headerMobileChildren = useHeaderMobileChildren();
   const headerLeftContent = useHeaderLeftContent();
+  const headerLogo = useHeaderLogo();
 
   return (
     <div className={`flex h-full w-full flex-col`} data-testid={testId}>
-      <Header leftContent={headerLeftContent}>{headerChildren}</Header>
+      <Header leftContent={headerLeftContent} logo={headerLogo} mobileChildren={headerMobileChildren}>
+        {headerChildren}
+      </Header>
       <main className={cn(`flex w-full flex-1 flex-col gap-y-4 pt-4 pl-4 pr-0`, className)}>{children}</main>
     </div>
   );

package/src/components/containers/RoundPageContainer.tsx

@@ -20,7 +20,7 @@ import {
 import { partitionTabs, Tab } from "@/components/containers";
 import { RoundPageContainerTitle } from "@/components/containers/RoundPageContainerTitle";
 import { Header } from "@/components/navigations";
-import { useHeaderChildren, useHeaderLeftContent } from "@/contexts";
+import { useHeaderChildren, useHeaderLeftContent, useHeaderLogo, useHeaderMobileChildren } from "@/contexts";
 import { useUrlRewriter } from "@/hooks";
 import { cn, useIsMobile } from "@/index";
 import { ModuleWithPermissions } from "@/permissions";
@@ -85,6 +85,8 @@ export function RoundPageContainer({
 }: RoundPageContainerProps) {
   const headerChildren = useHeaderChildren();
   const headerLeftContent = useHeaderLeftContent();
+  const headerLogo = useHeaderLogo();
+  const headerMobileChildren = useHeaderMobileChildren();
   const [showDetails, setShowDetailsState] = useState(false);
   const isMobile = useIsMobile();
   const [mounted, setMounted] = useState(false);
@@ -148,12 +150,17 @@ export function RoundPageContainer({
     [tabs],
   );
 
-  const isReady = mounted && isMobile !== undefined;
+  const isReady = mounted;
 
   if (!isReady) {
     return (
       <>
-        <Header leftContent={headerLeftContent} className="bg-sidebar border-0">
+        <Header
+          leftContent={headerLeftContent}
+          logo={headerLogo}
+          mobileChildren={headerMobileChildren}
+          className="bg-sidebar border-0"
+        >
           {headerChildren}
         </Header>
         <div className={cn("flex h-[calc(100vh-3rem)] w-full flex-col", isMobile ? "" : "p-2 pt-0 pl-0")}>
@@ -167,7 +174,12 @@ export function RoundPageContainer({
 
   return (
     <>
-      <Header leftContent={headerLeftContent} className="bg-sidebar border-0">
+      <Header
+        leftContent={headerLeftContent}
+        logo={headerLogo}
+        mobileChildren={headerMobileChildren}
+        className="bg-sidebar border-0"
+      >
         {headerChildren}
       </Header>
       <div className={cn(`flex h-[calc(100vh-3rem)] w-full flex-col`, isMobile ? "p-1 pt-0" : "p-2 pt-0 pl-0")}>

package/src/components/navigations/Header.tsx

@@ -8,11 +8,15 @@ import { BreadcrumbNavigation } from "./Breadcrumb";
 
 type HeaderProps = {
   children?: React.ReactNode;
+  /** Widgets kept on mobile, where there is no room for the full `children` set. */
+  mobileChildren?: React.ReactNode;
   leftContent?: React.ReactNode;
+  /** Rendered before everything else, on mobile only — where the sidebar (and its logo) is off-canvas. */
+  logo?: React.ReactNode;
   className?: string;
 };
 
-export function Header({ children, leftContent, className }: HeaderProps) {
+export function Header({ children, mobileChildren, leftContent, logo, className }: HeaderProps) {
   const { breadcrumbs } = useSharedContext();
   const rootLabel = useHeaderRootLabel();
   const isMobile = useIsMobile();
@@ -20,16 +24,23 @@ export function Header({ children, leftContent, className }: HeaderProps) {
   return (
     <header className={`sticky top-0 z-10 flex h-12 flex-col items-center justify-start gap-x-4 ${className ?? ""}`}>
       <div className="bg-sidebar flex h-12 w-full flex-row items-center justify-between pl-2 pr-4">
+        {isMobile && logo && <div className="flex shrink-0 flex-row items-center pr-1">{logo}</div>}
         <SidebarTrigger aria-label="Toggle sidebar" id="sidebar-trigger" />
         {leftContent}
         <div className="flex w-full flex-row items-center justify-start">
           <BreadcrumbNavigation items={breadcrumbs} rootLabel={rootLabel ?? undefined} />
         </div>
-        {!isMobile && children && (
-          <div className="flex w-64 flex-row items-center justify-end gap-x-4 whitespace-nowrap">
-            <div className="flex flex-row items-center justify-end gap-x-4 whitespace-nowrap">{children}</div>
-          </div>
-        )}
+        {isMobile
+          ? mobileChildren && (
+              <div className="flex shrink-0 flex-row items-center justify-end gap-x-2 whitespace-nowrap">
+                {mobileChildren}
+              </div>
+            )
+          : children && (
+              <div className="flex w-64 flex-row items-center justify-end gap-x-4 whitespace-nowrap">
+                <div className="flex flex-row items-center justify-end gap-x-4 whitespace-nowrap">{children}</div>
+              </div>
+            )}
       </div>
     </header>
   );

package/src/components/pages/PageContentContainer.tsx

@@ -21,7 +21,7 @@ export function PageContentContainer({ header, details, footer, content, fullBle
     setMounted(true);
   }, []);
 
-  const isReady = mounted && isMobile !== undefined;
+  const isReady = mounted;
 
   // Create layout ID based on device type for separate persistence
   const layoutId = `page-content-container-${isMobile ? "mobile" : "desktop"}`;

package/src/contexts/HeaderChildrenContext.tsx

@@ -4,17 +4,20 @@ import { createContext, useContext, ReactNode } from "react";
 
 interface HeaderChildrenContextType {
   headerChildren: ReactNode | null;
+  headerMobileChildren: ReactNode | null;
   headerRootLabel: string | null;
 }
 
 const HeaderChildrenContext = createContext<HeaderChildrenContextType>({
   headerChildren: null,
+  headerMobileChildren: null,
   headerRootLabel: null,
 });
 
 interface HeaderChildrenProviderProps {
   children: ReactNode;
   content: ReactNode;
+  mobileContent?: ReactNode;
   rootLabel?: string;
 }
 
@@ -22,10 +25,19 @@ interface HeaderChildrenProviderProps {
  * Provider to supply custom content to be rendered in the Header component.
  * Wrap your layout with this provider and pass the content you want in the header.
  * Optionally pass `rootLabel` to override the first breadcrumb entry (defaults to `common.home`).
+ *
+ * The header has far less room on mobile, so `content` is desktop-only. Pass `mobileContent`
+ * to choose which widgets survive there; omit it and the header stays bare on mobile.
  */
-export function HeaderChildrenProvider({ children, content, rootLabel }: HeaderChildrenProviderProps) {
+export function HeaderChildrenProvider({ children, content, mobileContent, rootLabel }: HeaderChildrenProviderProps) {
   return (
-    <HeaderChildrenContext.Provider value={{ headerChildren: content, headerRootLabel: rootLabel ?? null }}>
+    <HeaderChildrenContext.Provider
+      value={{
+        headerChildren: content,
+        headerMobileChildren: mobileContent ?? null,
+        headerRootLabel: rootLabel ?? null,
+      }}
+    >
       {children}
     </HeaderChildrenContext.Provider>
   );
@@ -40,6 +52,15 @@ export function useHeaderChildren(): ReactNode | null {
   return context.headerChildren;
 }
 
+/**
+ * Hook to get the header content the application wants kept on mobile.
+ * Returns null when the application supplied none, in which case the Header shows no widgets there.
+ */
+export function useHeaderMobileChildren(): ReactNode | null {
+  const context = useContext(HeaderChildrenContext);
+  return context.headerMobileChildren;
+}
+
 /**
  * Hook to get the label of the first breadcrumb entry, when the application supplies one.
  * Returns null when no override was provided, in which case the Header falls back to `common.home`.

package/src/contexts/HeaderLogoContext.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { createContext, useContext, ReactNode } from "react";
+
+interface HeaderLogoContextType {
+  headerLogo: ReactNode | null;
+}
+
+const HeaderLogoContext = createContext<HeaderLogoContextType>({
+  headerLogo: null,
+});
+
+interface HeaderLogoProviderProps {
+  children: ReactNode;
+  content: ReactNode;
+}
+
+export function HeaderLogoProvider({ children, content }: HeaderLogoProviderProps) {
+  return <HeaderLogoContext.Provider value={{ headerLogo: content }}>{children}</HeaderLogoContext.Provider>;
+}
+
+export function useHeaderLogo(): ReactNode | null {
+  const context = useContext(HeaderLogoContext);
+  return context.headerLogo;
+}

package/src/contexts/ViewportContext.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import * as React from "react";
+import { getViewportContext, measureViewport, persistViewport, subscribeViewport } from "../utils/use-mobile";
+
+/**
+ * Seeds the viewport from the server so SSR and the first client render agree,
+ * removing the desktop-then-mobile chrome flash.
+ *
+ * `initialIsMobile` comes from the request — cookie first (a real measurement
+ * from a previous visit), user agent as the first-visit fallback. See the
+ * (main)/(admin) layouts.
+ *
+ * THIS LIVES IN `contexts/`, NOT `utils/`, AND MUST STAY HERE. The server
+ * layouts render it directly, so it needs a genuine "use client" boundary in
+ * the BUILT output. tsup.config.ts stamps the directive onto `dist/contexts/*`
+ * via its `clientEntries` list; `dist/core/*` is deliberately excluded so that
+ * instrumentation can import it server-side. Exporting this provider from
+ * `core` therefore made Next execute it as a Server Component and fail with
+ * "createContext only works in Client Components".
+ *
+ * `SocketContext` in this directory is the reference: it is likewise rendered
+ * straight from `(main)/layout.tsx`, a Server Component, and works.
+ */
+export function ViewportProvider({
+  initialIsMobile,
+  children,
+}: {
+  initialIsMobile: boolean;
+  children: React.ReactNode;
+}) {
+  const ViewportContext = getViewportContext();
+  const [isMobile, setIsMobile] = React.useState<boolean>(initialIsMobile);
+
+  React.useEffect(
+    () =>
+      subscribeViewport(() => {
+        const next = measureViewport();
+        setIsMobile(next);
+        persistViewport(next);
+      }),
+    [],
+  );
+
+  return <ViewportContext.Provider value={isMobile}>{children}</ViewportContext.Provider>;
+}

package/src/contexts/index.ts

@@ -9,8 +9,10 @@ export * from "../features/assistant/contexts/AssistantContext";
 export * from "./CommonContext";
 export * from "./HeaderChildrenContext";
 export * from "./HeaderLeftContentContext";
+export * from "./HeaderLogoContext";
 export * from "./SharedContext";
 export * from "./SocketContext";
+export * from "./ViewportContext";
 
 // Jotai atoms (merged from /atoms entry point)
 export * from "../atoms";

package/src/core/registry/__tests__/viewportStore.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const VIEWPORT_CONTEXT_KEY = Symbol.for("nextjs-jsonapi:viewportContext");
+
+type GlobalStore = Record<symbol, unknown>;
+
+afterEach(() => {
+  vi.resetModules();
+});
+
+describe("viewportStore", () => {
+  /**
+   * Regression guard. `apps/web/src/instrumentation.ts` pulls this module into
+   * the Node/RSC server graph at startup (jsonapi.config -> Bootstrapper ->
+   * @carlonicora/nextjs-jsonapi/core -> utils barrel -> use-mobile ->
+   * viewportStore). React resolves to the vendored RSC build there, which omits
+   * `createContext`. A module-scope call crashed the dev server on boot with
+   * "createContext is not a function". Importing must stay side-effect free.
+   */
+  it("does not create the context merely by being imported", async () => {
+    const store = globalThis as unknown as GlobalStore;
+    const previous = store[VIEWPORT_CONTEXT_KEY];
+    delete store[VIEWPORT_CONTEXT_KEY];
+
+    try {
+      vi.resetModules();
+      await import("../viewportStore");
+      expect(store[VIEWPORT_CONTEXT_KEY]).toBeUndefined();
+    } finally {
+      store[VIEWPORT_CONTEXT_KEY] = previous;
+    }
+  });
+
+  it("creates the context on first call and returns a stable identity after", async () => {
+    const store = globalThis as unknown as GlobalStore;
+    const previous = store[VIEWPORT_CONTEXT_KEY];
+    delete store[VIEWPORT_CONTEXT_KEY];
+
+    try {
+      vi.resetModules();
+      const { getViewportContext } = await import("../viewportStore");
+
+      const first = getViewportContext();
+      expect(first).toBeDefined();
+      expect(getViewportContext()).toBe(first);
+    } finally {
+      store[VIEWPORT_CONTEXT_KEY] = previous;
+    }
+  });
+});

package/src/core/registry/viewportStore.ts

@@ -0,0 +1,47 @@
+"use client";
+
+/**
+ * Centralized viewport context object.
+ *
+ * Uses a globalThis Symbol key so that tsup's multi-entry `splitting: true`
+ * build cannot produce two distinct React context objects. If it did, a
+ * ViewportProvider from one bundle graph and a useIsMobile from another would
+ * silently miss each other: the hook would read `undefined`, fall back to the
+ * legacy path, and the flash would return with nothing failing loudly.
+ *
+ * CREATION IS LAZY, AND MUST STAY THAT WAY. Do not hoist the `createContext`
+ * call to module scope. `apps/web/src/instrumentation.ts` imports
+ * `jsonapi.config.ts` -> `Bootstrapper.ts` -> `@carlonicora/nextjs-jsonapi/core`,
+ * whose barrel re-exports `../utils` and therefore pulls this module into the
+ * Node/RSC server graph at server startup. In that graph Next resolves `react`
+ * to the vendored RSC build, which deliberately omits `createContext` because
+ * it is a client-only API. A module-scope call there crashes the dev server on
+ * boot with "createContext is not a function" — the `"use client"` directive
+ * does not help, because instrumentation is not a React render.
+ *
+ * Calling the accessor only from inside the provider/hook guarantees it runs in
+ * a rendering context, where `createContext` exists.
+ *
+ * NO external dependencies beyond React, to avoid circular imports.
+ *
+ * Pattern mirrors `helpStore.ts` / `bootstrapStore.ts`.
+ */
+
+import { createContext, type Context } from "react";
+
+const VIEWPORT_CONTEXT_KEY = Symbol.for("nextjs-jsonapi:viewportContext");
+
+const globalStore = globalThis as unknown as {
+  [VIEWPORT_CONTEXT_KEY]?: Context<boolean | undefined>;
+};
+
+/**
+ * Returns the process-wide viewport context, creating it on first use.
+ * Never call this at module scope — see the note above.
+ */
+export function getViewportContext(): Context<boolean | undefined> {
+  if (globalStore[VIEWPORT_CONTEXT_KEY] === undefined) {
+    globalStore[VIEWPORT_CONTEXT_KEY] = createContext<boolean | undefined>(undefined);
+  }
+  return globalStore[VIEWPORT_CONTEXT_KEY]!;
+}

package/src/utils/__tests__/use-mobile.test.tsx

@@ -0,0 +1,137 @@
+import { render, screen, act } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { useIsMobile, VIEWPORT_COOKIE_NAME } from "../use-mobile";
+// The provider lives in `contexts/` (not `utils/`) because the server layouts
+// render it directly and only `dist/contexts/*` gets tsup's "use client" banner.
+import { ViewportProvider } from "../../contexts/ViewportContext";
+
+function Probe() {
+  const isMobile = useIsMobile();
+  return <span data-testid="probe">{isMobile ? "mobile" : "desktop"}</span>;
+}
+
+function setWidth(width: number) {
+  Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: width });
+}
+
+beforeEach(() => {
+  setWidth(1280);
+  document.cookie = `${VIEWPORT_COOKIE_NAME}=; path=/; max-age=0`;
+  vi.mocked(window.matchMedia).mockClear();
+});
+
+describe("server-graph safety", () => {
+  /**
+   * Regression guard. This module is reachable from the RSC/Node graph:
+   * apps/web instrumentation.ts -> jsonapi.config -> Bootstrapper ->
+   * @carlonicora/nextjs-jsonapi/core -> utils barrel -> use-mobile.
+   * Creating the context at module scope crashed the dev server on boot
+   * ("createContext is not a function"), because React resolves to the
+   * vendored RSC build there. Importing must stay side-effect free.
+   */
+  it("does not create the context merely by being imported", async () => {
+    const key = Symbol.for("nextjs-jsonapi:viewportContext");
+    const store = globalThis as unknown as Record<symbol, unknown>;
+    const previous = store[key];
+    delete store[key];
+
+    try {
+      vi.resetModules();
+      await import("../use-mobile");
+      expect(store[key]).toBeUndefined();
+    } finally {
+      store[key] = previous;
+      vi.resetModules();
+    }
+  });
+
+  it("creates the context on first call and returns a stable identity after", async () => {
+    const key = Symbol.for("nextjs-jsonapi:viewportContext");
+    const store = globalThis as unknown as Record<symbol, unknown>;
+    const previous = store[key];
+    delete store[key];
+
+    try {
+      vi.resetModules();
+      const { getViewportContext } = await import("../use-mobile");
+      const first = getViewportContext();
+      expect(first).toBeDefined();
+      expect(getViewportContext()).toBe(first);
+    } finally {
+      store[key] = previous;
+      vi.resetModules();
+    }
+  });
+});
+
+describe("useIsMobile with a ViewportProvider", () => {
+  it("returns the server seed on the first render, before any measurement", () => {
+    setWidth(1280);
+    const seen: string[] = [];
+    function Recorder() {
+      const isMobile = useIsMobile();
+      seen.push(isMobile ? "mobile" : "desktop");
+      return null;
+    }
+    render(
+      <ViewportProvider initialIsMobile={true}>
+        <Recorder />
+      </ViewportProvider>,
+    );
+    expect(seen[0]).toBe("mobile");
+  });
+
+  it("corrects a wrong seed after mounting and persists the measurement", () => {
+    setWidth(1280);
+    render(
+      <ViewportProvider initialIsMobile={true}>
+        <Probe />
+      </ViewportProvider>,
+    );
+    expect(screen.getByTestId("probe").textContent).toBe("desktop");
+    expect(document.cookie).toContain(`${VIEWPORT_COOKIE_NAME}=0`);
+  });
+
+  it("keeps a correct seed and persists it", () => {
+    setWidth(500);
+    render(
+      <ViewportProvider initialIsMobile={true}>
+        <Probe />
+      </ViewportProvider>,
+    );
+    expect(screen.getByTestId("probe").textContent).toBe("mobile");
+    expect(document.cookie).toContain(`${VIEWPORT_COOKIE_NAME}=1`);
+  });
+
+  it("follows a viewport change through the matchMedia listener", () => {
+    setWidth(1280);
+    render(
+      <ViewportProvider initialIsMobile={false}>
+        <Probe />
+      </ViewportProvider>,
+    );
+    expect(screen.getByTestId("probe").textContent).toBe("desktop");
+
+    const mql = vi.mocked(window.matchMedia).mock.results[0].value;
+    const handler = mql.addEventListener.mock.calls[0][1] as () => void;
+    setWidth(500);
+    act(() => handler());
+
+    expect(screen.getByTestId("probe").textContent).toBe("mobile");
+  });
+});
+
+describe("useIsMobile without a provider (legacy fallback)", () => {
+  it("measures the viewport itself and does not write a cookie", () => {
+    setWidth(500);
+    render(<Probe />);
+    expect(screen.getByTestId("probe").textContent).toBe("mobile");
+    expect(document.cookie).not.toContain(`${VIEWPORT_COOKIE_NAME}=`);
+  });
+
+  it("reports desktop for a wide viewport", () => {
+    setWidth(1280);
+    render(<Probe />);
+    expect(screen.getByTestId("probe").textContent).toBe("desktop");
+  });
+});

package/src/utils/index.ts

@@ -1,7 +1,7 @@
 export type { ClassValue } from "clsx";
 export { cn } from "./cn";
 export { composeRefs, useComposedRefs } from "./compose-refs";
-export { useIsMobile } from "./use-mobile";
+export { useIsMobile, MOBILE_BREAKPOINT, VIEWPORT_COOKIE_NAME } from "./use-mobile";
 
 // New utilities
 export { formatDate, formatLocalDate, type FormatOption } from "./date-formatter";

package/src/utils/use-mobile.tsx

@@ -2,20 +2,77 @@
 
 import * as React from "react";
 
-const MOBILE_BREAKPOINT = 768;
+export const MOBILE_BREAKPOINT = 768;
+export const VIEWPORT_COOKIE_NAME = "viewport_mobile";
 
-export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined);
+/**
+ * The viewport context is keyed on a globalThis Symbol so that tsup's
+ * multi-entry `splitting: true` build cannot produce two distinct context
+ * objects. If it did, the ViewportProvider (built into the `contexts` entry)
+ * and this hook (built into the `core` entry) would silently miss each other:
+ * the hook would read `undefined`, fall back to the legacy path, and the
+ * mobile-layout flash would return with nothing failing loudly.
+ *
+ * THIS MODULE IS SERVER-REACHABLE. `core` is deliberately absent from
+ * tsup.config.ts's `clientEntries` list, so `dist/core/*` gets NO "use client"
+ * banner — that is what lets `apps/web/src/instrumentation.ts` import
+ * jsonapi.config -> Bootstrapper -> `@carlonicora/nextjs-jsonapi/core` at
+ * server startup. Two rules follow, both load-bearing:
+ *
+ * 1. React is imported as a NAMESPACE. A named
+ *    `import { createContext } from "react"` makes Turbopack statically refuse
+ *    the module: "You're importing a module that depends on `createContext`
+ *    into a React Server Component module."
+ * 2. Creation is LAZY, never at module scope. On the server React resolves to
+ *    the vendored RSC build, which omits `createContext` entirely
+ *    ("createContext is not a function" — crashes the dev server at boot).
+ *
+ * `useIsMobile` only ever runs inside a Client Component render, so calling the
+ * accessor from there is safe. The PROVIDER must not live here — it is rendered
+ * by the server layouts, so it needs a real "use client" boundary and therefore
+ * lives in `contexts/ViewportContext.tsx`.
+ */
+const VIEWPORT_CONTEXT_KEY = Symbol.for("nextjs-jsonapi:viewportContext");
+
+const globalStore = globalThis as unknown as {
+  [VIEWPORT_CONTEXT_KEY]?: React.Context<boolean | undefined>;
+};
+
+/** Returns the process-wide viewport context, creating it on first use. */
+export function getViewportContext(): React.Context<boolean | undefined> {
+  if (globalStore[VIEWPORT_CONTEXT_KEY] === undefined) {
+    globalStore[VIEWPORT_CONTEXT_KEY] = React.createContext<boolean | undefined>(undefined);
+  }
+  return globalStore[VIEWPORT_CONTEXT_KEY]!;
+}
+
+/** @internal — consumed by contexts/ViewportContext.tsx */
+export function measureViewport(): boolean {
+  return window.innerWidth < MOBILE_BREAKPOINT;
+}
+
+/** @internal — consumed by contexts/ViewportContext.tsx */
+export function persistViewport(isMobile: boolean): void {
+  document.cookie = `${VIEWPORT_COOKIE_NAME}=${isMobile ? "1" : "0"}; path=/; max-age=31536000; samesite=lax`;
+}
+
+/** @internal — consumed by contexts/ViewportContext.tsx */
+export function subscribeViewport(onChange: () => void): () => void {
+  const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+  onChange();
+  mql.addEventListener("change", onChange);
+  return () => mql.removeEventListener("change", onChange);
+}
+
+export function useIsMobile(): boolean {
+  const seeded = React.useContext(getViewportContext());
+  const [legacy, setLegacy] = React.useState<boolean>(false);
 
   React.useEffect(() => {
-    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
-    const onChange = () => {
-      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
-    };
-    mql.addEventListener("change", onChange);
-    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
-    return () => mql.removeEventListener("change", onChange);
-  }, []);
-
-  return !!isMobile;
+    // A provider owns the value; never run the legacy measurement alongside it.
+    if (seeded !== undefined) return;
+    return subscribeViewport(() => setLegacy(measureViewport()));
+  }, [seeded]);
+
+  return seeded ?? legacy;
 }