@carlonicora/nextjs-jsonapi 1.133.0 → 1.135.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/navigations/MobileNavigationBar.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useMobileNavigationItems, type MobileNavigationItem } from "../../contexts/MobileNavigationContext";
+import { Link } from "../../shadcnui";
+import { cn } from "../../utils/cn";
+import { useIsMobile } from "../../utils/use-mobile";
+
+/**
+ * Active only for navigational slots.
+ *
+ * Exact-or-prefix, NOT a bare `startsWith`: the prefix arm keeps a detail route
+ * (/accounts/123) highlighting its section (/accounts).
+ *
+ * "/" is special-cased to EXACT match. Without that, its prefix arm degenerates
+ * to `pathname.startsWith("/")`, which is true for every route, and the Home
+ * slot highlights everywhere. This is pinned by a unit test in Task C.
+ */
+function isActiveHref(pathname: string, href: string): boolean {
+  if (href === "/") return pathname === "/";
+  return pathname === href || pathname.startsWith(`${href}/`);
+}
+
+const slotClass = cn(
+  // min-h-12/min-w-12 = 48px touch target (Material/HIG guidance).
+  "relative flex min-h-12 min-w-12 flex-1 items-center justify-center",
+  "transition-colors",
+);
+
+function SlotContent({ item }: { item: MobileNavigationItem }) {
+  if (item.render) return <>{item.render}</>;
+  const Icon = item.icon;
+  return Icon ? <Icon className="size-6" /> : null;
+}
+
+/**
+ * The mobile bottom navigation bar.
+ *
+ * Renders nothing on desktop, and nothing when the application supplied no
+ * items — so page containers can render it unconditionally.
+ *
+ * Rendered as an in-flow flex sibling of the page content (NOT position:fixed),
+ * so the content column shrinks to fit and can never be hidden behind the bar.
+ */
+export function MobileNavigationBar() {
+  const items = useMobileNavigationItems();
+  const isMobile = useIsMobile();
+  const pathname = usePathname();
+
+  if (!isMobile || items.length === 0) return null;
+
+  // A detached surface sitting BELOW the page card with a gap, so it carries a
+  // rounded border rather than a `border-t`, which would read as if the bar were
+  // welded to the card's bottom edge. `bg-sidebar` deliberately matches the
+  // Header's own background so the two chrome edges of the viewport agree.
+  return (
+    <nav
+      aria-label="Primary"
+      data-testid="mobile-navigation-bar"
+      className="bg-sidebar flex w-full shrink-0 flex-row items-stretch rounded-lg border pb-[env(safe-area-inset-bottom)]"
+    >
+      {items.map((item) => {
+        const active = item.href ? isActiveHref(pathname, item.href) : false;
+        const tone = active ? "text-primary" : "text-muted-foreground";
+
+        const body = (
+          <>
+            {active && <span aria-hidden className="bg-primary absolute inset-x-0 top-0 h-0.5" />}
+            <SlotContent item={item} />
+          </>
+        );
+
+        return item.href ? (
+          <Link
+            key={item.key}
+            href={item.href}
+            aria-label={item.label}
+            aria-current={active ? "page" : undefined}
+            data-testid={`mobile-nav-${item.key}`}
+            className={cn(slotClass, tone)}
+          >
+            {body}
+          </Link>
+        ) : (
+          <button
+            key={item.key}
+            type="button"
+            onClick={item.onClick}
+            aria-label={item.label}
+            data-testid={`mobile-nav-${item.key}`}
+            className={cn(slotClass, tone)}
+          >
+            {body}
+          </button>
+        );
+      })}
+    </nav>
+  );
+}

package/src/components/navigations/__tests__/MobileNavigationBar.spec.tsx

@@ -0,0 +1,131 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { HomeIcon, SearchIcon } from "lucide-react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { MobileNavigationProvider, type MobileNavigationItem } from "../../../contexts/MobileNavigationContext";
+import { ViewportProvider } from "../../../contexts/ViewportContext";
+import { configureI18n } from "../../../i18n";
+import { MobileNavigationBar } from "../MobileNavigationBar";
+
+// usePathname is globally mocked to "/" in vitest.setup.ts. Override it here so
+// the active-state rule can be exercised against a real route. A spec-level
+// vi.mock takes precedence over the setup-file mock for this module.
+const pathnameRef = { current: "/" };
+vi.mock("next/navigation", () => ({
+  usePathname: () => pathnameRef.current,
+  useRouter: () => ({
+    push: vi.fn(),
+    replace: vi.fn(),
+    prefetch: vi.fn(),
+    back: vi.fn(),
+    forward: vi.fn(),
+    refresh: vi.fn(),
+  }),
+  useSearchParams: () => new URLSearchParams(),
+  useParams: () => ({}),
+  redirect: vi.fn(),
+  notFound: vi.fn(),
+}));
+
+beforeAll(() => {
+  // The package Link resolves its inner component at runtime and throws if i18n
+  // was never configured (src/i18n/config.ts:53-58).
+  configureI18n({
+    useRouter: () => ({
+      push: vi.fn(),
+      replace: vi.fn(),
+      back: vi.fn(),
+      forward: vi.fn(),
+      refresh: vi.fn(),
+      prefetch: vi.fn(),
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => pathnameRef.current,
+    Link: ({ href, children, ...rest }: { href: string; children: React.ReactNode; [key: string]: any }) => (
+      <a href={href} {...rest}>
+        {children}
+      </a>
+    ),
+  });
+});
+
+beforeEach(() => {
+  pathnameRef.current = "/";
+  // jsdom defaults to 1024; ViewportProvider's effect measures immediately and
+  // would otherwise overwrite the mobile seed with "desktop".
+  Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 375 });
+});
+
+function renderBar(items: MobileNavigationItem[], { mobile = true }: { mobile?: boolean } = {}) {
+  if (!mobile) {
+    Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 1024 });
+  }
+  return render(
+    <ViewportProvider initialIsMobile={mobile}>
+      <MobileNavigationProvider items={items}>
+        <MobileNavigationBar />
+      </MobileNavigationProvider>
+    </ViewportProvider>,
+  );
+}
+
+const searchItem: MobileNavigationItem = { key: "search", label: "Cerca", icon: SearchIcon, onClick: vi.fn() };
+const homeItem: MobileNavigationItem = { key: "home", label: "Dashboard", icon: HomeIcon, href: "/" };
+
+describe("MobileNavigationBar", () => {
+  it("renders nothing when the application supplied no items", () => {
+    renderBar([]);
+    expect(screen.queryByTestId("mobile-navigation-bar")).not.toBeInTheDocument();
+  });
+
+  it("renders nothing on desktop even when items exist", () => {
+    renderBar([searchItem], { mobile: false });
+    expect(screen.queryByTestId("mobile-navigation-bar")).not.toBeInTheDocument();
+  });
+
+  it("renders one slot per item, labelled by its accessible name", () => {
+    renderBar([searchItem, homeItem]);
+    expect(screen.getByTestId("mobile-navigation-bar")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Cerca" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Dashboard" })).toBeInTheDocument();
+  });
+
+  it("does not render the label as visible text (icons-only bar)", () => {
+    renderBar([searchItem]);
+    expect(screen.queryByText("Cerca")).not.toBeInTheDocument();
+  });
+
+  it("fires onClick for action slots", async () => {
+    const onClick = vi.fn();
+    renderBar([{ ...searchItem, onClick }]);
+    await userEvent.click(screen.getByRole("button", { name: "Cerca" }));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it("renders the `render` escape hatch instead of an icon", () => {
+    renderBar([
+      { key: "profile", label: "Impostazioni", render: <span data-testid="avatar-stub" />, href: "/settings" },
+    ]);
+    expect(screen.getByTestId("avatar-stub")).toBeInTheDocument();
+  });
+
+  // The load-bearing case: a bare startsWith would make href="/" match everything.
+  it("marks only the exactly-matching slot active when one href is '/'", () => {
+    pathnameRef.current = "/conversations";
+    renderBar([homeItem, { key: "ai", label: "Chiedi all'AI", icon: SearchIcon, href: "/conversations" }]);
+    expect(screen.getByRole("link", { name: "Dashboard" })).not.toHaveAttribute("aria-current");
+    expect(screen.getByRole("link", { name: "Chiedi all'AI" })).toHaveAttribute("aria-current", "page");
+  });
+
+  it("keeps a section active on its detail route", () => {
+    pathnameRef.current = "/conversations/abc-123";
+    renderBar([{ key: "ai", label: "Chiedi all'AI", icon: SearchIcon, href: "/conversations" }]);
+    expect(screen.getByRole("link", { name: "Chiedi all'AI" })).toHaveAttribute("aria-current", "page");
+  });
+
+  it("never marks an action slot active", () => {
+    pathnameRef.current = "/";
+    renderBar([searchItem]);
+    expect(screen.getByRole("button", { name: "Cerca" })).not.toHaveAttribute("aria-current");
+  });
+});

package/src/components/navigations/index.ts

@@ -1,6 +1,7 @@
 export * from "./Breadcrumb";
 export * from "./ContentTitle";
 export * from "./Header";
+export * from "./MobileNavigationBar";
 export * from "./ModeToggleSwitch";
 export * from "./PageSection";
 export * from "./RecentPagesNavigator";

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/MobileNavigationContext.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import * as React from "react";
+import type { ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * One slot in the mobile bottom navigation bar.
+ *
+ * Supply exactly one of `icon` / `render`, and exactly one of `href` / `onClick`.
+ * This is a review-time contract, not a runtime-validated one — the mistake is
+ * immediately visible in dev, and validation code would ship to every consumer.
+ *
+ * `render` content MUST NOT contain an interactive element: an `href` slot is
+ * already wrapped in a <Link>, so a nested <a>/<button> is invalid HTML and
+ * triggers a hydration error.
+ */
+export type MobileNavigationItem = {
+  /** Stable unique key. Used as the React key and the `data-testid` suffix. */
+  key: string;
+  /** Accessible name. The bar is icons-only, so this is never rendered as text. */
+  label: string;
+  /** Rendered at 24px. Mutually exclusive with `render`. */
+  icon?: LucideIcon;
+  /** Escape hatch for slots an icon cannot express (logo mark, user avatar). */
+  render?: ReactNode;
+  /** Navigational slot — receives the active highlight. */
+  href?: string;
+  /** Action slot — never highlighted. */
+  onClick?: () => void;
+};
+
+/**
+ * A plain module-scope context, mirroring the sibling `HeaderChildrenContext`.
+ *
+ * The `globalThis`-Symbol lazy-creation dance in `utils/use-mobile.tsx` is NOT
+ * needed here: that exists for the `core` entry, which is deliberately excluded
+ * from tsup's `clientEntries` and is reachable from server code. Provider (the
+ * `contexts` entry) and consumer (the `components` entry) share one context
+ * object, exactly as `HeaderChildrenContext` already does in production.
+ */
+const MobileNavigationContext = React.createContext<MobileNavigationItem[]>([]);
+
+/**
+ * Supplies the items rendered by `MobileNavigationBar`.
+ *
+ * Unlike `useSharedContext`, the hook below does NOT throw without a provider —
+ * it returns `[]` and the bar renders nothing. Apps that never install this
+ * provider are completely unaffected.
+ *
+ * MUST be rendered inside `ViewportProvider` so the bar's `useIsMobile()` reads
+ * the server-seeded viewport rather than flashing.
+ */
+export function MobileNavigationProvider({ children, items }: { children: ReactNode; items: MobileNavigationItem[] }) {
+  // Items are rebuilt on every render of the app-side provider (it depends on
+  // hooks); memoising on the array identity keeps consumers from re-rendering
+  // more than the parent already does.
+  const value = React.useMemo(() => items, [items]);
+
+  return <MobileNavigationContext.Provider value={value}>{children}</MobileNavigationContext.Provider>;
+}
+
+/** Returns the application-supplied bottom-navigation items, or `[]` when none. */
+export function useMobileNavigationItems(): MobileNavigationItem[] {
+  return React.useContext(MobileNavigationContext);
+}

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,11 @@ export * from "../features/assistant/contexts/AssistantContext";
 export * from "./CommonContext";
 export * from "./HeaderChildrenContext";
 export * from "./HeaderLeftContentContext";
+export * from "./HeaderLogoContext";
+export * from "./MobileNavigationContext";
 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]!;
+}