@carlonicora/nextjs-jsonapi 1.132.0 → 1.134.0

package/dist/server/index.js

@@ -15,7 +15,7 @@ var _chunkIOLU4ASDjs = require('../chunk-IOLU4ASD.js');
 
 
 
-var _chunk5IE6DZ2Djs = require('../chunk-5IE6DZ2D.js');
+var _chunkW73JBOIRjs = require('../chunk-W73JBOIR.js');
 require('../chunk-LXKSUWAV.js');
 require('../chunk-IBS6NI7D.js');
 
@@ -86,7 +86,7 @@ var ServerSession = class {
     if (!rawModules) return false;
     const modules = JSON.parse(_pako2.default.ungzip(Buffer.from(rawModules, "base64"), { to: "string" }));
     const selectedModule = modules.find((module) => module.id === params.module.moduleId);
-    return _chunk5IE6DZ2Djs.checkPermissionsFromServer.call(void 0, {
+    return _chunkW73JBOIRjs.checkPermissionsFromServer.call(void 0, {
       module: params.module,
       action: params.action,
       data: params.data,
@@ -296,5 +296,5 @@ _chunk7QVYU63Ejs.__name.call(void 0, ServerJsonApiDelete, "ServerJsonApiDelete")
 
 
 
-exports.ServerAuthService = _chunk5IE6DZ2Djs.AuthService; exports.ServerCompanyService = _chunk5IE6DZ2Djs.CompanyService; exports.ServerContentService = _chunk5IE6DZ2Djs.ContentService; exports.ServerFeatureService = _chunk5IE6DZ2Djs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk5IE6DZ2Djs.NotificationService; exports.ServerPushService = _chunk5IE6DZ2Djs.PushService; exports.ServerRoleService = _chunk5IE6DZ2Djs.RoleService; exports.ServerS3Service = _chunk5IE6DZ2Djs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk5IE6DZ2Djs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
+exports.ServerAuthService = _chunkW73JBOIRjs.AuthService; exports.ServerCompanyService = _chunkW73JBOIRjs.CompanyService; exports.ServerContentService = _chunkW73JBOIRjs.ContentService; exports.ServerFeatureService = _chunkW73JBOIRjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunkW73JBOIRjs.NotificationService; exports.ServerPushService = _chunkW73JBOIRjs.PushService; exports.ServerRoleService = _chunkW73JBOIRjs.RoleService; exports.ServerS3Service = _chunkW73JBOIRjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunkW73JBOIRjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
 //# sourceMappingURL=index.js.map

package/dist/server/index.mjs

@@ -15,7 +15,7 @@ import {
   S3Service,
   UserService,
   checkPermissionsFromServer
-} from "../chunk-DZL2G7NB.mjs";
+} from "../chunk-DVOBOFCF.mjs";
 import "../chunk-AUXK7QSA.mjs";
 import "../chunk-C7C7VY4F.mjs";
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.132.0",
+  "version": "1.134.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

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/components/tables/ContentListTable.tsx

@@ -10,6 +10,7 @@ import React, { ReactNode, memo, useMemo, useState } from "react";
 import { DataListRetriever, TableContent, useTableGenerator } from "../../hooks";
 import { ModuleWithPermissions } from "../../permissions";
 import { Button, Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow } from "../../shadcnui";
+import { MicroLabel } from "../typography";
 import { ContentTableSearch } from "./ContentTableSearch";
 
 const EMPTY_ARRAY: any[] = [];
@@ -49,6 +50,9 @@ type ContentListTableProps = {
   defaultExpanded?: boolean | ExpandedState;
   fullWidth?: boolean;
   groupBy?: string;
+  groupLabel?: (key: string) => ReactNode;
+  groupOrder?: string[];
+  hideHeader?: boolean;
   emptyState?: ReactNode;
   onRowClick?: (rowData: any) => void;
 };
@@ -118,12 +122,24 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
       }
     }
 
-    const sortedKeys = [...groupMap.keys()].sort((a, b) => a.localeCompare(b));
+    const order = props.groupOrder;
+    const sortedKeys = [...groupMap.keys()].sort((a, b) => {
+      if (order) {
+        const ia = order.indexOf(a);
+        const ib = order.indexOf(b);
+        // keys absent from groupOrder sort last, alphabetically among themselves
+        if (ia === -1 && ib === -1) return a.localeCompare(b);
+        if (ia === -1) return 1;
+        if (ib === -1) return -1;
+        return ia - ib;
+      }
+      return a.localeCompare(b);
+    });
     return sortedKeys.map((groupKey) => ({
       groupKey,
       rows: groupMap.get(groupKey)!,
     }));
-  }, [props.groupBy, rowModel]);
+  }, [props.groupBy, props.groupOrder, rowModel]);
 
   const showFooter = !!(data.next || data.previous);
 
@@ -168,18 +184,19 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
                 </TableHead>
               </TableRow>
             )}
-            {table.getHeaderGroups().map((headerGroup) => (
-              <TableRow key={headerGroup.id}>
-                {headerGroup.headers.map((header) => {
-                  const meta = header.column.columnDef.meta as { className?: string } | undefined;
-                  return (
-                    <TableHead key={header.id} className={meta?.className}>
-                      {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
-                    </TableHead>
-                  );
-                })}
-              </TableRow>
-            ))}
+            {!props.hideHeader &&
+              table.getHeaderGroups().map((headerGroup) => (
+                <TableRow key={headerGroup.id}>
+                  {headerGroup.headers.map((header) => {
+                    const meta = header.column.columnDef.meta as { className?: string } | undefined;
+                    return (
+                      <TableHead key={header.id} className={meta?.className}>
+                        {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
+                      </TableHead>
+                    );
+                  })}
+                </TableRow>
+              ))}
           </TableHeader>
           <TableBody>
             {rowModel && rowModel.rows?.length ? (
@@ -187,11 +204,8 @@ export const ContentListTable = memo(function ContentListTable(props: ContentLis
                 groupedRows.map((group) => (
                   <React.Fragment key={group.groupKey}>
                     <TableRow>
-                      <TableCell
-                        colSpan={tableColumns.length}
-                        className="bg-muted text-muted-foreground px-4 py-2 text-sm font-semibold"
-                      >
-                        {group.groupKey}
+                      <TableCell colSpan={tableColumns.length} className="bg-muted px-4 py-2">
+                        <MicroLabel>{props.groupLabel?.(group.groupKey) ?? group.groupKey}</MicroLabel>
                       </TableCell>
                     </TableRow>
                     {group.rows.map((row) => (

package/src/components/tables/__tests__/ContentListTable.test.tsx

@@ -338,6 +338,37 @@ describe("ContentListTable", () => {
     });
   });
 
+  describe("hideHeader", () => {
+    it("should render the column header row by default", () => {
+      const dataRetriever = createMockDataRetriever({
+        data: [{ id: "1", title: "Article 1" }],
+      });
+
+      render(<ContentListTable data={dataRetriever} tableGeneratorType={mockModule as any} fields={["id", "title"]} />);
+
+      expect(screen.getByText("Title")).toBeInTheDocument();
+    });
+
+    it("should not render the column header row when hideHeader is set", () => {
+      const dataRetriever = createMockDataRetriever({
+        data: [{ id: "1", title: "Article 1" }],
+      });
+
+      render(
+        <ContentListTable
+          data={dataRetriever}
+          tableGeneratorType={mockModule as any}
+          fields={["id", "title"]}
+          hideHeader
+        />,
+      );
+
+      expect(screen.queryByText("Title")).not.toBeInTheDocument();
+      // Body rows must still render — only the header row is suppressed.
+      expect(screen.getByText("Article 1")).toBeInTheDocument();
+    });
+  });
+
   describe("grouping", () => {
     it("should not group rows when groupBy is not provided", () => {
       const dataRetriever = createMockDataRetriever({
@@ -511,6 +542,52 @@ describe("ContentListTable", () => {
       const article3Count = allText.filter((t) => t === "Article 3").length;
       expect(article3Count).toBe(2);
     });
+
+    it("should render group headers through groupLabel when provided", () => {
+      const dataRetriever = createMockDataRetriever({
+        data: [
+          { id: "1", title: "Article 1", category: "CIVIL" },
+          { id: "2", title: "Article 2", category: "CRIMINAL" },
+        ],
+      });
+
+      render(
+        <ContentListTable
+          data={dataRetriever}
+          tableGeneratorType={mockModule as any}
+          fields={["id", "title"]}
+          groupBy="category"
+          groupLabel={(key) => `Branch: ${key}`}
+        />,
+      );
+
+      expect(screen.getByText("Branch: CIVIL")).toBeInTheDocument();
+      expect(screen.getByText("Branch: CRIMINAL")).toBeInTheDocument();
+      expect(screen.queryByText("CIVIL")).not.toBeInTheDocument();
+    });
+
+    it("should order groups by groupOrder instead of alphabetically", () => {
+      const dataRetriever = createMockDataRetriever({
+        data: [
+          { id: "1", title: "A Article", category: "A" },
+          { id: "2", title: "B Article", category: "B" },
+          { id: "3", title: "C Article", category: "C" },
+        ],
+      });
+
+      render(
+        <ContentListTable
+          data={dataRetriever}
+          tableGeneratorType={mockModule as any}
+          fields={["id", "title"]}
+          groupBy="category"
+          groupOrder={["C", "A", "B"]}
+        />,
+      );
+
+      const headings = screen.getAllByRole("heading", { level: 4 });
+      expect(headings.map((h) => h.textContent)).toEqual(["C", "A", "B"]);
+    });
   });
 
   describe("onRowClick", () => {

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]!;
+}