@carlonicora/nextjs-jsonapi 1.108.0 → 1.109.0

package/src/features/help/components/__tests__/HelpHint.spec.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpHint } from "../HelpHint";
+
+const article = {
+  id: "1",
+  slug: "x",
+  mode: "how-to",
+  title: "X",
+  summary: "S",
+  order: 1,
+  tags: [],
+  contextualKeys: ["npc.editor"],
+  aiIndexed: true,
+  draft: false,
+  contentHash: "h",
+  path: "how-to/x.mdx",
+  headings: [],
+  relatedSlugs: [],
+  lastUpdated: "2026-01-01T00:00:00Z",
+};
+
+beforeEach(() => {
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { manifest: [article], namespaceUuid: "00000000-0000-5000-8000-000000000000" },
+  });
+});
+
+describe("HelpHint", () => {
+  it("renders null when no article matches the contextKey", () => {
+    const { container } = render(
+      <HelpProvider>
+        <HelpHint contextKey="nope.absent" />
+      </HelpProvider>,
+    );
+    expect(container.querySelector("button")).toBeNull();
+  });
+
+  it("renders the trigger when at least one article matches", () => {
+    render(
+      <HelpProvider>
+        <HelpHint contextKey="npc.editor" />
+      </HelpProvider>,
+    );
+    expect(screen.getByLabelText(/help on this|hint/i)).toBeTruthy();
+  });
+});

package/src/features/help/components/__tests__/HelpSearchResultRow.spec.tsx

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Command, CommandList } from "../../../../shadcnui";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpSearchResultRow } from "../HelpSearchResultRow";
+
+const article = {
+  id: "abc",
+  slug: "x",
+  mode: "how-to" as const,
+  title: "X title",
+  summary: "S",
+  order: 1,
+  tags: [],
+  contextualKeys: [],
+  aiIndexed: true,
+  draft: false,
+  contentHash: "h",
+  path: "how-to/x.mdx",
+  headings: [],
+  relatedSlugs: [],
+  lastUpdated: "2026-01-01T00:00:00Z",
+};
+
+beforeEach(() => {
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { manifest: [article], namespaceUuid: "00000000-0000-5000-8000-000000000000" },
+  });
+});
+
+describe("HelpSearchResultRow", () => {
+  it("renders the article title when manifest contains the id", () => {
+    render(
+      <HelpProvider>
+        <Command>
+          <CommandList>
+            <HelpSearchResultRow result={{ id: "abc", name: "ignored", entityType: "howtos" }} />
+          </CommandList>
+        </Command>
+      </HelpProvider>,
+    );
+    expect(screen.getByText("X title")).toBeTruthy();
+  });
+
+  it("renders disabled removed-state row when id is missing", () => {
+    render(
+      <HelpProvider>
+        <Command>
+          <CommandList>
+            <HelpSearchResultRow result={{ id: "ghost", name: "ignored", entityType: "howtos" }} />
+          </CommandList>
+        </Command>
+      </HelpProvider>,
+    );
+    expect(screen.queryByText("X title")).toBeNull();
+  });
+});

package/src/features/help/components/__tests__/HelpSideNav.spec.tsx

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpSideNav } from "../HelpSideNav";
+
+const base = {
+  tags: [],
+  contextualKeys: [],
+  aiIndexed: true,
+  draft: false,
+  contentHash: "h",
+  headings: [],
+  relatedSlugs: [],
+  lastUpdated: "2026-01-01T00:00:00Z",
+};
+
+beforeEach(() => {
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: {
+      manifest: [
+        { ...base, id: "a", slug: "a", mode: "how-to", title: "Alpha", summary: "s", order: 1, path: "how-to/a.mdx" },
+        { ...base, id: "b", slug: "b", mode: "how-to", title: "Beta", summary: "s", order: 2, path: "how-to/b.mdx" },
+      ],
+      namespaceUuid: "00000000-0000-5000-8000-000000000000",
+    },
+  });
+});
+
+describe("HelpSideNav", () => {
+  it("lists every non-draft article", () => {
+    render(
+      <HelpProvider>
+        <HelpSideNav />
+      </HelpProvider>,
+    );
+    expect(screen.getByText("Alpha")).toBeTruthy();
+    expect(screen.getByText("Beta")).toBeTruthy();
+  });
+
+  it("filters by query", () => {
+    render(
+      <HelpProvider>
+        <HelpSideNav />
+      </HelpProvider>,
+    );
+    fireEvent.change(screen.getByPlaceholderText(/filter/i), { target: { value: "Bet" } });
+    expect(screen.queryByText("Alpha")).toBeNull();
+    expect(screen.getByText("Beta")).toBeTruthy();
+  });
+});

package/src/features/help/components/mdx/Callout.tsx

@@ -0,0 +1,21 @@
+import { InfoIcon, AlertTriangleIcon, LightbulbIcon, XCircleIcon, LucideIcon } from "lucide-react";
+import { ReactNode } from "react";
+
+type CalloutType = "info" | "warning" | "tip" | "danger";
+
+const STYLES: Record<CalloutType, { icon: LucideIcon; ring: string }> = {
+  info: { icon: InfoIcon, ring: "ring-blue-500/30 bg-blue-500/5" },
+  warning: { icon: AlertTriangleIcon, ring: "ring-amber-500/30 bg-amber-500/5" },
+  tip: { icon: LightbulbIcon, ring: "ring-emerald-500/30 bg-emerald-500/5" },
+  danger: { icon: XCircleIcon, ring: "ring-rose-500/30 bg-rose-500/5" },
+};
+
+export function Callout({ type = "info", children }: { type?: CalloutType; children: ReactNode }) {
+  const { icon: Icon, ring } = STYLES[type];
+  return (
+    <div className={`my-4 flex gap-3 rounded-md ring-1 p-3 ${ring}`}>
+      <Icon className="mt-0.5 h-4 w-4 shrink-0" />
+      <div className="text-sm leading-relaxed">{children}</div>
+    </div>
+  );
+}

package/src/features/help/components/mdx/EntityRef.tsx

@@ -0,0 +1,18 @@
+import { Modules } from "../../../../core";
+import { ReactNode } from "react";
+
+export function EntityRef({ type, children }: { type: string; children: ReactNode }) {
+  let Icon: React.ComponentType<{ className?: string }> | null = null;
+  try {
+    const m = Modules.findByName(type);
+    Icon = m.icon ?? null;
+  } catch {
+    Icon = null;
+  }
+  return (
+    <span className="bg-muted text-foreground/90 inline-flex items-center gap-1 rounded px-1.5 py-0.5 align-middle text-xs">
+      {Icon ? <Icon className="h-3 w-3" /> : null}
+      {children}
+    </span>
+  );
+}

package/src/features/help/components/mdx/KeyBinding.tsx

@@ -0,0 +1,6 @@
+import { ReactNode } from "react";
+export function KeyBinding({ children }: { children: ReactNode }) {
+  return (
+    <kbd className="bg-muted text-muted-foreground rounded border px-1.5 py-0.5 text-xs font-medium">{children}</kbd>
+  );
+}

package/src/features/help/components/mdx/Related.tsx

@@ -0,0 +1,33 @@
+"use client";
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import { useHelp } from "../../contexts/HelpContext";
+import { usePageUrlGenerator } from "../../../../client";
+import { articleUrl } from "../../utils/articleUrl";
+
+export function Related({ slugs }: { slugs: string[] }) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const { manifest } = useHelp();
+  const items = slugs
+    .map((s) => manifest.find((a) => `${a.mode}/${a.slug}` === s))
+    .filter((a): a is NonNullable<typeof a> => Boolean(a));
+  if (items.length === 0) return null;
+  return (
+    <aside className="my-6">
+      <h3 className="text-muted-foreground mb-2 text-xs font-semibold tracking-wider uppercase">
+        {t("help.article.related")}
+      </h3>
+      <ul className="grid gap-2 sm:grid-cols-2">
+        {items.map((a) => (
+          <li key={a.id}>
+            <Link href={articleUrl(generateUrl, a)} className="hover:bg-muted block rounded border p-3">
+              <div className="font-medium">{a.title}</div>
+              <div className="text-muted-foreground text-xs">{a.summary}</div>
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </aside>
+  );
+}

package/src/features/help/components/mdx/Screenshot.tsx

@@ -0,0 +1,9 @@
+export function Screenshot({ src, alt, caption }: { src: string; alt?: string; caption?: string }) {
+  const url = src.startsWith("/") ? src : `/help-assets/${src}`;
+  return (
+    <figure className="my-4">
+      <img src={url} alt={alt ?? caption ?? ""} className="rounded-md ring-1 ring-border" />
+      {caption ? <figcaption className="text-muted-foreground mt-1 text-xs">{caption}</figcaption> : null}
+    </figure>
+  );
+}

package/src/features/help/components/mdx/Steps.tsx

@@ -0,0 +1,21 @@
+import { ReactNode, Children } from "react";
+
+export function Steps({ children }: { children: ReactNode }) {
+  const items = Children.toArray(children);
+  return (
+    <ol className="my-4 list-none space-y-3 pl-0">
+      {items.map((child, i) => (
+        <li key={i} className="flex gap-3">
+          <span className="bg-muted text-muted-foreground flex h-6 w-6 shrink-0 items-center justify-center rounded-full text-xs">
+            {i + 1}
+          </span>
+          <div className="flex-1 [&>p:first-child]:mt-0">{child}</div>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function Step({ children }: { children: ReactNode }) {
+  return <>{children}</>;
+}

package/src/features/help/components/mdx/Video.tsx

@@ -0,0 +1,8 @@
+export function Video({ src, poster }: { src: string; poster?: string }) {
+  const url = src.startsWith("/") ? src : `/help-assets/${src}`;
+  return (
+    <video controls preload="metadata" poster={poster} className="my-4 w-full rounded-md ring-1 ring-border">
+      <source src={url} />
+    </video>
+  );
+}

package/src/features/help/components/mdx/mdx-server-components.ts

@@ -0,0 +1,23 @@
+// Server-safe subset of MDX_COMPONENTS used by `renderHelpArticle`.
+// Mirrors `mdxComponents.ts` but EXCLUDES `Related` (which is a client
+// component that uses `useHelp` + `usePageUrlGenerator`). Server-side rendering
+// of `<Related>` would require passing the manifest by prop, which the standard
+// MDX components map cannot do — articles that need related links should be
+// extended via a server-side render hook rather than the MDX shortcode.
+
+import { Callout } from "./Callout";
+import { Steps, Step } from "./Steps";
+import { Screenshot } from "./Screenshot";
+import { EntityRef } from "./EntityRef";
+import { KeyBinding } from "./KeyBinding";
+import { Video } from "./Video";
+
+export const MDX_SERVER_COMPONENTS = {
+  Callout,
+  Steps,
+  Step,
+  Screenshot,
+  EntityRef,
+  KeyBinding,
+  Video,
+} as const;

package/src/features/help/components/mdx/mdxComponents.ts

@@ -0,0 +1,9 @@
+import { Callout } from "./Callout";
+import { Steps, Step } from "./Steps";
+import { Screenshot } from "./Screenshot";
+import { EntityRef } from "./EntityRef";
+import { KeyBinding } from "./KeyBinding";
+import { Video } from "./Video";
+import { Related } from "./Related";
+
+export const MDX_COMPONENTS = { Callout, Steps, Step, Screenshot, EntityRef, KeyBinding, Video, Related };

package/src/features/help/contexts/HelpContext.spec.tsx

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { ReactNode } from "react";
+import { configureJsonApi } from "../../../client/config";
+import { HelpProvider, useHelp } from "./HelpContext";
+
+describe("HelpProvider / useHelp", () => {
+  const cfg = {
+    manifest: [],
+    namespaceUuid: "00000000-0000-5000-8000-000000000000",
+    brand: { logo: "/logo.png", label: "Test", appHref: "/" },
+  };
+
+  beforeEach(() => {
+    configureJsonApi({ apiUrl: "http://localhost", helpContent: cfg });
+  });
+
+  it("exposes the configured helpContent via useHelp()", () => {
+    const wrapper = ({ children }: { children: ReactNode }) => <HelpProvider>{children}</HelpProvider>;
+    const { result } = renderHook(() => useHelp(), { wrapper });
+    expect(result.current.manifest).toBe(cfg.manifest);
+    expect(result.current.brand?.label).toBe("Test");
+  });
+
+  it("throws when useHelp() is called outside HelpProvider", () => {
+    expect(() => renderHook(() => useHelp())).toThrow(/outside <HelpProvider>/);
+  });
+});

package/src/features/help/contexts/HelpContext.tsx

@@ -0,0 +1,24 @@
+"use client";
+import { createContext, useContext, ReactNode } from "react";
+import { _getStaticHelpContent } from "../../../core/registry/helpStore";
+import type { HelpContentConfig } from "../interfaces/help-content-config.interface";
+
+const HelpContext = createContext<HelpContentConfig | null>(null);
+
+export function HelpProvider({ children }: { children: ReactNode }) {
+  const cfg = _getStaticHelpContent<HelpContentConfig>();
+  if (!cfg) {
+    throw new Error(
+      "Help content not configured — call configureJsonApi({ helpContent: {...} }) before importing help components.",
+    );
+  }
+  return <HelpContext.Provider value={cfg}>{children}</HelpContext.Provider>;
+}
+
+export function useHelp(): HelpContentConfig {
+  const ctx = useContext(HelpContext);
+  if (!ctx) {
+    throw new Error("useHelp() called outside <HelpProvider>. Wrap your help route group with <HelpProvider>.");
+  }
+  return ctx;
+}

package/src/features/help/hooks/useHelp.ts

@@ -0,0 +1 @@
+export { useHelp } from "../contexts/HelpContext";

package/src/features/help/hooks/useHelpArticle.ts

@@ -0,0 +1,7 @@
+"use client";
+import { useHelp } from "../contexts/HelpContext";
+import { findHelpArticle } from "../utils/helpNavigation";
+
+export function useHelpArticle(mode: string, slug: string) {
+  return findHelpArticle(useHelp().manifest, mode, slug);
+}

package/src/features/help/hooks/useHelpFilter.ts

@@ -0,0 +1,27 @@
+"use client";
+import { useMemo, useState } from "react";
+import Fuse from "fuse.js";
+import type { HelpArticle } from "../types/help-article.types";
+
+export function useHelpFilter(articles: readonly HelpArticle[]) {
+  const [query, setQuery] = useState("");
+  const fuse = useMemo(
+    () =>
+      new Fuse([...articles], {
+        keys: [
+          { name: "title", weight: 0.5 },
+          { name: "summary", weight: 0.3 },
+          { name: "tags", weight: 0.1 },
+          { name: "headings.text", weight: 0.1 },
+        ],
+        threshold: 0.4,
+        ignoreLocation: true,
+      }),
+    [articles],
+  );
+  const filtered = useMemo(() => {
+    if (!query.trim()) return [...articles];
+    return fuse.search(query).map((r) => r.item);
+  }, [query, articles, fuse]);
+  return { query, setQuery, filtered };
+}

package/src/features/help/hooks/useHelpManifest.ts

@@ -0,0 +1,5 @@
+"use client";
+import { useHelp } from "../contexts/HelpContext";
+export function useHelpManifest() {
+  return useHelp().manifest;
+}

package/src/features/help/i18n-keys.ts

@@ -0,0 +1,34 @@
+/**
+ * The fixed namespace of i18n keys this feature reads via useTranslations/getTranslations.
+ * Consuming apps must define each entry in their messages/<locale>.json.
+ */
+export const HELP_I18N_KEYS = [
+  "help.modes.tutorial",
+  "help.modes.how-to",
+  "help.modes.reference",
+  "help.modes.explanation",
+  "help.sideNav.filterPlaceholder",
+  "help.sideNav.noMatches",
+  "help.toc.title",
+  "help.article.lastUpdated",
+  "help.article.previous",
+  "help.article.next",
+  "help.article.related",
+  "help.askAi.button",
+  "help.askAi.loginTooltip",
+  "help.askAi.sheet.title",
+  "help.askAi.sheet.subtitle",
+  "help.header.search",
+  "help.header.login",
+  "help.header.openApp",
+  "help.hint.trigger",
+  "help.hint.viewArticle",
+  "help.hint.pickArticle",
+  "help.landing.heading",
+  "help.landing.subheading",
+  "help.landing.featuredTutorials",
+  "help.landing.browseByMode",
+  "help.modeIndex.empty",
+  "help.search.removed",
+  "help.footerLink",
+] as const;

package/src/features/help/index.ts

@@ -0,0 +1,27 @@
+// Client-only public barrel for the help feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/help`. Tsup adds a top-level
+// "use client" directive to the bundled output via clientEntries.
+//
+// Pair this with `@carlonicora/nextjs-jsonapi/help/server` (server) for the
+// pure server utilities (serializeHelpArticle, generate*StaticParams, etc.).
+// Consumers compose page shells themselves: import the client primitives below
+// (HelpProvider, HelpHeader, HelpSideNav, HelpArticleBody, HelpTOC, etc.) and
+// the server utilities from /help/server, then assemble pages in app routes.
+
+export { HelpProvider, useHelp } from "./contexts/HelpContext";
+export { HelpHeader } from "./components/HelpHeader";
+export { HelpSideNav } from "./components/HelpSideNav";
+export { HelpArticleBody } from "./components/HelpArticleBody";
+export { HelpTOC } from "./components/HelpTOC";
+export { HelpHint } from "./components/HelpHint";
+export { HelpAskAi } from "./components/HelpAskAi";
+export { HelpSearchResultRow } from "./components/HelpSearchResultRow";
+export { MDX_COMPONENTS } from "./components/mdx/mdxComponents";
+export { useHelpManifest } from "./hooks/useHelpManifest";
+export { useHelpArticle } from "./hooks/useHelpArticle";
+export { useHelpFilter } from "./hooks/useHelpFilter";
+export { articleUrl, modeUrl } from "./utils/articleUrl";
+export { HELP_I18N_KEYS } from "./i18n-keys";
+export type { HelpContentConfig, HelpBrandConfig } from "./interfaces/help-content-config.interface";
+export { HELP_MODES } from "./types/help-article.types";
+export type { HelpArticle, HelpHeading, HelpMode, HelpRedirect } from "./types/help-article.types";

package/src/features/help/interfaces/help-content-config.interface.ts

@@ -0,0 +1,17 @@
+import type { HelpArticle, HelpRedirect } from "../types/help-article.types";
+
+export interface HelpBrandConfig {
+  /** URL of the brand logo image (served by the consuming app). */
+  logo?: string;
+  /** Brand label shown in the help header. */
+  label?: string;
+  /** Where the "Open app" button navigates for logged-in users. Defaults to "/". */
+  appHref?: string;
+}
+
+export interface HelpContentConfig {
+  manifest: readonly HelpArticle[];
+  namespaceUuid: string;
+  redirects?: readonly HelpRedirect[];
+  brand?: HelpBrandConfig;
+}

package/src/features/help/server/__tests__/createHelpAssetRouteHandler.spec.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHelpAssetRouteHandler } from "../createHelpAssetRouteHandler";
+
+describe("createHelpAssetRouteHandler", () => {
+  let srcRoot: string;
+
+  beforeAll(async () => {
+    srcRoot = await mkdtemp(join(tmpdir(), "help-assets-"));
+    await mkdir(srcRoot, { recursive: true });
+    await writeFile(join(srcRoot, "ok.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+  });
+  afterAll(async () => {
+    await rm(srcRoot, { recursive: true, force: true });
+  });
+
+  it("returns 200 with correct MIME for an existing PNG", async () => {
+    const GET = createHelpAssetRouteHandler({ srcRoot });
+    const res = await GET(new Request("http://localhost/help-assets/ok.png"), {
+      params: Promise.resolve({ path: ["ok.png"] }),
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/png");
+  });
+
+  it("returns 404 for missing files", async () => {
+    const GET = createHelpAssetRouteHandler({ srcRoot });
+    const res = await GET(new Request("http://localhost/help-assets/missing.png"), {
+      params: Promise.resolve({ path: ["missing.png"] }),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("sanitizes path traversal attempts", async () => {
+    const GET = createHelpAssetRouteHandler({ srcRoot });
+    const res = await GET(new Request("http://localhost/help-assets/etc/passwd"), {
+      params: Promise.resolve({ path: ["..", "..", "etc", "passwd"] }),
+    });
+    expect(res.status).toBe(404);
+  });
+});

package/src/features/help/server/createHelpAssetRouteHandler.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from "next/server";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+const MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+};
+
+export function createHelpAssetRouteHandler({ srcRoot }: { srcRoot: string }) {
+  return async function GET(_req: Request, { params }: { params: Promise<{ path: string[] }> }) {
+    const { path } = await params;
+    const safe = path.filter((p) => p !== ".." && !p.includes("/")).join("/");
+    const filePath = join(srcRoot, safe);
+    try {
+      const s = await stat(filePath);
+      if (!s.isFile()) return new NextResponse("Not found", { status: 404 });
+      const ext = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
+      const mime = MIME[ext] ?? "application/octet-stream";
+      const data = await readFile(filePath);
+      return new NextResponse(data, {
+        status: 200,
+        headers: { "Content-Type": mime, "Cache-Control": "public, max-age=3600" },
+      });
+    } catch {
+      return new NextResponse("Not found", { status: 404 });
+    }
+  };
+}

package/src/features/help/server/generateHelpArticleMetadata.ts

@@ -0,0 +1,18 @@
+import type { Metadata } from "next";
+import { findHelpArticle } from "../utils/helpNavigation";
+import { getHelpContent } from "./getHelpContent";
+
+export async function generateHelpArticleMetadata({
+  params,
+}: {
+  params: Promise<{ mode: string; slug: string }>;
+}): Promise<Metadata> {
+  const { mode, slug } = await params;
+  const article = findHelpArticle(getHelpContent().manifest, mode, slug);
+  if (!article) return {};
+  return {
+    title: article.title,
+    description: article.summary,
+    openGraph: { title: article.title, description: article.summary },
+  };
+}

package/src/features/help/server/generateHelpArticleStaticParams.ts

@@ -0,0 +1,7 @@
+import { getHelpContent } from "./getHelpContent";
+
+export function generateHelpArticleStaticParams(): { mode: string; slug: string }[] {
+  return getHelpContent()
+    .manifest.filter((a) => !a.draft)
+    .map((a) => ({ mode: a.mode, slug: a.slug }));
+}

package/src/features/help/server/generateHelpModeStaticParams.ts

@@ -0,0 +1,5 @@
+import { HELP_MODES } from "../types/help-article.types";
+
+export function generateHelpModeStaticParams(): { mode: string }[] {
+  return HELP_MODES.map((mode) => ({ mode }));
+}

package/src/features/help/server/getHelpContent.ts

@@ -0,0 +1,17 @@
+import { _getStaticHelpContent } from "../../../core/registry/helpStore";
+import type { HelpContentConfig } from "../interfaces/help-content-config.interface";
+
+/**
+ * Server-side accessor for the help-content config set via configureJsonApi().
+ * Returns the same value <HelpProvider> exposes via React Context to client components.
+ * Throws with a setup error if helpContent was never configured.
+ */
+export function getHelpContent(): HelpContentConfig {
+  const cfg = _getStaticHelpContent<HelpContentConfig>();
+  if (!cfg) {
+    throw new Error(
+      "Help content not configured — call configureJsonApi({ helpContent: {...} }) before importing help pages.",
+    );
+  }
+  return cfg;
+}

package/src/features/help/server/index.ts

@@ -0,0 +1,8 @@
+export { getHelpContent } from "./getHelpContent";
+export { renderHelpArticle, serializeHelpArticle } from "./serializeHelpArticle";
+export { generateHelpArticleStaticParams } from "./generateHelpArticleStaticParams";
+export { generateHelpArticleMetadata } from "./generateHelpArticleMetadata";
+export { generateHelpModeStaticParams } from "./generateHelpModeStaticParams";
+// NOTE: `createHelpAssetRouteHandler` is intentionally NOT re-exported here.
+// It uses `node:fs/promises` and must only be reachable via the dedicated
+// `@carlonicora/nextjs-jsonapi/help-asset-route` subpath, never the main bundle.