@nextsparkjs/core 0.1.0-beta.189 → 0.1.0-beta.190

package/templates/contents/themes/starter/blocks/text-content/schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod'
+import * as z from 'zod'
 import { baseBlockSchema } from '@nextsparkjs/core/types/blocks'
 
 /**

package/templates/contents/themes/starter/entities/posts/components/post-header.tsx

@@ -1,4 +1,5 @@
 import { Badge } from '@nextsparkjs/core/components/ui/badge'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 import Image from 'next/image'
 
 interface Category {
@@ -24,7 +25,7 @@ export function PostHeader({ post }: PostHeaderProps) {
       {post.featuredImage && (
         <div className="relative w-full h-[400px] md:h-[500px] mb-8" data-cy="post-featured-image-display">
           <Image
-            src={post.featuredImage}
+            src={withBasePathIfInApp(post.featuredImage)}
             alt={post.title}
             fill
             className="object-cover rounded-lg"

package/templates/contents/themes/starter/lib/hooks/useAnalyticsData.ts

@@ -2,6 +2,7 @@
 
 import { useQuery } from '@tanstack/react-query'
 import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
+import { withBasePath } from '@nextsparkjs/core/lib/base-path'
 
 interface WeeklyProgress {
   day: string
@@ -31,7 +32,7 @@ export function useAnalyticsData() {
   return useQuery({
     queryKey: ['analytics', currentTeam?.id],
     queryFn: async (): Promise<AnalyticsData> => {
-      const res = await fetch(`/api/v1/analytics?teamId=${currentTeam?.id}`)
+      const res = await fetch(withBasePath(`/api/v1/analytics?teamId=${currentTeam?.id}`))
       if (!res.ok) throw new Error('Failed to fetch analytics')
       return res.json()
     },

package/templates/contents/themes/starter/lib/hooks/useTaskStats.ts

@@ -4,6 +4,7 @@ import { useMemo } from 'react'
 import { useQuery } from '@tanstack/react-query'
 import { useTeamContext } from '@nextsparkjs/core/contexts/TeamContext'
 import { calculateTaskStats, type TaskStats } from '../utils'
+import { withBasePath } from '@nextsparkjs/core/lib/base-path'
 
 interface Task {
   id: string
@@ -32,7 +33,7 @@ export function useTaskStats(): UseTaskStatsReturn {
   } = useQuery({
     queryKey: ['tasks', currentTeam?.id, 'stats'],
     queryFn: async (): Promise<Task[]> => {
-      const response = await fetch(`/api/v1/tasks?teamId=${currentTeam?.id}&limit=1000`)
+      const response = await fetch(withBasePath(`/api/v1/tasks?teamId=${currentTeam?.id}&limit=1000`))
       if (!response.ok) {
         throw new Error('Failed to fetch tasks')
       }

package/templates/eslint.config.mjs

@@ -1,16 +1,140 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
 
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
+/**
+ * Next's presets from the eslint-config-next the project installs, as flat config.
+ *
+ * Version 16 publishes flat config arrays on these subpaths; reaching them through FlatCompat
+ * throws `Converting circular structure to JSON` before a single file is read. Version 15 declares
+ * no `exports` and publishes eslintrc presets, which FlatCompat is the only way to read: importing
+ * the subpaths throws ERR_MODULE_NOT_FOUND, or, under a loader that adds file extensions, returns
+ * eslintrc objects. That is what a Next 15 project gets when `nextspark init` drops this file next
+ * to its eslint-config-next. FlatCompat ships in @eslint/eslintrc, which ESLint itself depends on,
+ * so it is resolved from there.
+ */
+async function nextPresets() {
+  let presets;
+  try {
+    presets = await Promise.all([
+      import("eslint-config-next/core-web-vitals"),
+      import("eslint-config-next/typescript"),
+    ]);
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND") throw error;
+  }
+
+  if (presets?.every((preset) => Array.isArray(preset.default))) {
+    return presets.flatMap((preset) => preset.default);
+  }
+
+  const { FlatCompat } = createRequire(require.resolve("eslint"))("@eslint/eslintrc");
+  return new FlatCompat({ baseDirectory: __dirname }).extends("next/core-web-vitals", "next/typescript");
+}
+
+/** A config object holding nothing but `ignores` applies to every other object in the array. */
+const isGlobalIgnore = (config) =>
+  Object.keys(config).every((key) => key === "ignores" || key === "name");
+
+const presets = await nextPresets();
+
+/** typescript-eslint's parser, which reads every syntax these trees use: JS, TS and JSX. */
+const typescriptParser = presets
+  .map((config) => config.languageOptions?.parser)
+  .find((parser) => parser?.meta?.name === "typescript-eslint/parser");
+
+const SOURCE_FILES = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
+
+// Tests and fixtures, the project's own and those every theme and plugin brings under contents/:
+// they mock, stub and cast by design, so Next's presets skip them and only the zod rule reaches
+// them. Everything else -- app/, contents/ and what the project adds -- gets the presets.
+const TEST_FILES = [
+  "**/tests/**",
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/fixtures/**",
+  "**/cypress/**",
+  "**/*.{test,spec,cy}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+  "**/{jest,cypress}.{config,setup}.{ts,mts,cts,js,mjs,cjs}",
+];
+
+/** "error", 2 or ["error", ...]. */
+const isError = (setting) => [setting, setting?.[0]].some((level) => level === "error" || level === 2);
+
+/**
+ * The severity this project gives the rules Next's presets configure.
+ *
+ * `@next/next/no-img-element` is an error: the presets only warn, which leaves `eslint .` passing,
+ * and next/image is what serves an image resized and in a modern format.
+ *
+ * eslint-plugin-react-hooks 7, which Next 16's presets load, adds to rules-of-hooks and
+ * exhaustive-deps the rules that flag code the React Compiler cannot compile. A NextSpark project
+ * does not build with the React Compiler, and the components NextSpark ships in app/ and its themes
+ * and plugins break several of those rules, so they report as warnings. Version 5, which Next 15
+ * loads, has none of them.
+ */
+function projectSeverity(rule, setting) {
+  if (rule === "@next/next/no-img-element") return "error";
+  const compilerRule = rule.startsWith("react-hooks/") && !["react-hooks/rules-of-hooks", "react-hooks/exhaustive-deps"].includes(rule);
+  return compilerRule && isError(setting) ? "warn" : setting;
+}
 
 const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    // Next writes next-env.d.ts itself; version 16's presets ignore it and version 15's do not.
+    ignores: [".next/**", ".nextspark/**", "next-env.d.ts"],
+  },
+  ...presets.map((config) =>
+    isGlobalIgnore(config)
+      ? config
+      : {
+          ...config,
+          ignores: [...(config.ignores ?? []), ...TEST_FILES],
+          ...(config.rules && {
+            rules: Object.fromEntries(Object.entries(config.rules).map(([rule, setting]) => [rule, projectSeverity(rule, setting)])),
+          }),
+        },
+  ),
+  {
+    // A .cjs file is CommonJS by definition, so `require` is the only spelling it has.
+    files: ["**/*.cjs"],
+    ignores: TEST_FILES,
+    rules: { "@typescript-eslint/no-require-imports": "off" },
+  },
+  {
+    // The presets would have supplied the parser here. Their plugins are registered so the disable
+    // comments in tests resolve the rules they name, without turning any of those rules on.
+    files: TEST_FILES,
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+    plugins: Object.assign({}, ...presets.map((config) => config.plugins ?? {})),
+    linterOptions: { reportUnusedDisableDirectives: "off" },
+  },
+  {
+    // Spelled out rather than inherited: a block naming these extensions is what makes ESLint lint
+    // a .ts file at all.
+    files: [SOURCE_FILES],
+    rules: {
+      // `no-restricted-imports` with `importNames: ["z"]` also rejects `import * as z`, so the
+      // named specifier is matched by syntax instead.
+      "no-restricted-syntax": [
+        "error",
+        {
+          // `imported` is an Identifier for `{ z }` and a Literal for `{ "z" as zod }`, so the
+          // name lives under a different property in each.
+          selector:
+            "ImportDeclaration[source.value='zod'] > ImportSpecifier:matches([imported.name='z'], [imported.value='z']), ExportNamedDeclaration[source.value='zod'] > ExportSpecifier:matches([local.name='z'], [local.value='z'])",
+          message:
+            "Use `import * as z from 'zod'`. Turbopack doesn't tree-shake the named `z` import and bundles all of zod, its 63 locales included.",
+        },
+      ],
+    },
+  },
 ];
 
 export default eslintConfig;

package/templates/features/blog/blocks/post-content/component.tsx

@@ -4,6 +4,7 @@ import { buildSectionClasses } from '@nextsparkjs/core/types/blocks'
 import { sanitizeBlockHtml } from '@nextsparkjs/core/lib/blocks/sanitize-html'
 import { sel } from '../../lib/selectors'
 import type { PostContentBlockProps } from './schema'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 
 /**
  * Post Content Block Component
@@ -182,7 +183,7 @@ export function PostContentBlock({
         {cta && (
           <div className={cn('mt-12 text-center', maxWidthClasses[maxWidth], 'mx-auto')}>
             <a
-              href={cta.link}
+              href={withBasePathIfInApp(cta.link)}
               target={cta.target}
               rel={cta.target === '_blank' ? 'noopener noreferrer' : undefined}
               className="inline-flex items-center justify-center rounded-md bg-primary px-8 py-3 text-sm font-medium text-primary-foreground hover:bg-primary/90 transition-colors shadow-md hover:shadow-lg"

package/templates/features/blog/blocks/post-content/schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod'
+import * as z from 'zod'
 import { baseBlockSchema } from '@nextsparkjs/core/types/blocks'
 
 /**

package/templates/features/blog/entities/posts/components/post-header.tsx

@@ -1,4 +1,5 @@
 import { Badge } from '@nextsparkjs/core/components/ui/badge'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 import Image from 'next/image'
 
 interface Category {
@@ -24,7 +25,7 @@ export function PostHeader({ post }: PostHeaderProps) {
       {post.featuredImage && (
         <div className="relative w-full h-[400px] md:h-[500px] mb-8" data-cy="post-featured-image-display">
           <Image
-            src={post.featuredImage}
+            src={withBasePathIfInApp(post.featuredImage)}
             alt={post.title}
             fill
             className="object-cover rounded-lg"

package/templates/features/pages/blocks/hero/component.tsx

@@ -4,6 +4,7 @@ import { cn } from '@nextsparkjs/core/lib/utils'
 import { buildSectionClasses, resolveMediaUrl } from '@nextsparkjs/core/types/blocks'
 import { sel } from '../../lib/selectors'
 import type { HeroBlockProps } from './schema'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 
 /**
  * Hero Block Component
@@ -71,7 +72,7 @@ export function HeroBlock({
         <div
           className="absolute inset-0 z-0"
           style={{
-            backgroundImage: `url(${backgroundImageUrl})`,
+            backgroundImage: `url(${withBasePathIfInApp(backgroundImageUrl)})`,
             backgroundSize: 'cover',
             backgroundPosition: 'center',
           }}
@@ -100,7 +101,7 @@ export function HeroBlock({
         {ctaConfig && (
           <Button asChild size="lg" className="text-lg px-8 py-6">
             <a
-              href={ctaConfig.link}
+              href={withBasePathIfInApp(ctaConfig.link)}
               target={ctaConfig.target}
               rel={ctaConfig.target === '_blank' ? 'noopener noreferrer' : undefined}
               data-cy={sel('blocks.hero.cta')}

package/templates/features/pages/blocks/hero/schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod'
+import * as z from 'zod'
 import {
   baseBlockSchema,
   mediaRefSchema,

package/templates/next.config.mjs

@@ -8,8 +8,52 @@ const __dirname = path.dirname(__filename);
 // For npm mode, use local i18n.ts that re-exports from @nextsparkjs/core
 const withNextIntl = createNextIntlPlugin('./i18n.ts');
 
+// The app's Next.js basePath. Next.js adds it to routes and to <Link>, and to
+// nothing a header names: the CSP report endpoints below are URLs the browser
+// resolves against the origin, so they carry it from here.
+const basePath = '';
+
+/**
+ * Silences the Node built-ins that client bundles reach transitively, and points
+ * `@nextsparkjs/registries` at the generated directory.
+ *
+ * Only webpack reads this, and either major can build with it: Next 15 by
+ * default, Next 16 with `--webpack`. Turbopack resolves `@nextsparkjs/registries`
+ * through the `paths` of tsconfig.json, which Next's webpack skips for imports
+ * made from inside node_modules, as core's are, and leaves a Node built-in alone
+ * unless client code imports it for real.
+ */
+const applyWebpackFallbacks = (config, { isServer }) => {
+  if (!isServer) {
+    config.resolve.fallback = {
+      ...config.resolve.fallback,
+      fs: false,
+      net: false,
+      tls: false,
+      crypto: false,
+      path: false,
+      os: false,
+      stream: false,
+      http: false,
+      https: false,
+      zlib: false,
+      dns: false,
+    }
+  }
+
+  // Add alias for @nextsparkjs/registries to fix ChunkLoadError
+  config.resolve.alias = {
+    ...config.resolve.alias,
+    'pg-native': false,
+    '@nextsparkjs/registries': path.resolve(__dirname, '.nextspark/registries'),
+  }
+
+  return config
+}
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  basePath,
   // Ignore TypeScript build errors - needed until DTS generation is enabled for @nextsparkjs/core
   // Without this, production builds fail due to missing declaration files for deep imports
   typescript: {
@@ -81,33 +125,10 @@ const nextConfig = {
       },
     ],
   },
-  webpack: (config, { isServer }) => {
-    if (!isServer) {
-      config.resolve.fallback = {
-        ...config.resolve.fallback,
-        fs: false,
-        net: false,
-        tls: false,
-        crypto: false,
-        path: false,
-        os: false,
-        stream: false,
-        http: false,
-        https: false,
-        zlib: false,
-        dns: false,
-      }
-    }
-
-    // Add alias for @nextsparkjs/registries to fix ChunkLoadError
-    config.resolve.alias = {
-      ...config.resolve.alias,
-      'pg-native': false,
-      '@nextsparkjs/registries': path.resolve(__dirname, '.nextspark/registries'),
-    }
-
-    return config
-  },
+  // Next.js sets TURBOPACK before it loads this file whenever Turbopack builds
+  // (on 15 with --turbopack, on 16 unless given --webpack), and next-intl picks
+  // its own webpack or Turbopack setup from the same variable.
+  ...(process.env.TURBOPACK ? {} : { webpack: applyWebpackFallbacks }),
   async headers() {
     const isProduction = process.env.NODE_ENV === 'production';
 
@@ -158,7 +179,7 @@ const nextConfig = {
       // CSP violation reporting - sends violations to /api/csp-report
       // report-uri is deprecated but has wider browser support
       // report-to is the modern replacement (configured via Reporting-Endpoints header)
-      "report-uri /api/csp-report",
+      `report-uri ${basePath}/api/csp-report`,
       "report-to csp-endpoint",
     ];
 
@@ -167,7 +188,7 @@ const nextConfig = {
       // Reporting API endpoint for modern browsers (used by report-to CSP directive)
       {
         key: 'Reporting-Endpoints',
-        value: 'csp-endpoint="/api/csp-report"'
+        value: `csp-endpoint="${basePath}/api/csp-report"`
       },
       {
         key: 'X-Content-Type-Options',

package/templates/proxy.ts

@@ -1,9 +1,8 @@
 /**
- * @nextspark-generated
- *
- * `nextspark sync:app` replaces this file while that tag is present, which is
- * how a release ships changes to it. Delete the tag line to own the file: from
- * then on sync reports it and leaves it alone.
+ * `nextspark sync:app` keeps this file up to date while its first line is the
+ * generated tag sync writes and the rest of the file is unchanged since then,
+ * which is how a release ships changes to it. Edit the file, or delete that
+ * line, to own it: from then on sync reports it and leaves it alone.
  *
  * NextSpark Proxy (Next.js 16+)
  *
@@ -12,9 +11,10 @@
  *
  * Key responsibilities:
  * 1. Theme middleware override support
- * 2. Documentation access control
- * 3. Protected route authentication, and the roles /superadmin and /devtools need
- * 4. User header injection for downstream use (x-user-id, x-pathname, x-active-team-id)
+ * 2. Redirecting historical 3-level docs URLs to their current route
+ * 3. Documentation access control
+ * 4. Protected route authentication, and the roles /superadmin and /devtools need
+ * 5. User header injection for downstream use (x-user-id, x-pathname, x-active-team-id)
  *
  * IMPORTANT: The EntityPermissionLayout depends on x-user-id and x-pathname
  * headers being set here for server-side permission validation.
@@ -28,6 +28,8 @@ import {
 } from '@nextsparkjs/core/lib/middleware'
 import { ACTIVE_TEAM_COOKIE, activeTeamIdForSession } from '@nextsparkjs/core/lib/teams/active-team-cookie'
 import { SESSION_HINT_COOKIE, SESSION_HINT_MAX_AGE, hasSessionCookie } from '@nextsparkjs/core/lib/auth/session-hint'
+import { isDocsPublic, legacyDocsAccessMessage } from '@nextsparkjs/core/lib/docs/access'
+import { DOCS_REGISTRY } from '@nextsparkjs/registries/docs-registry'
 
 /**
  * Session type for proxy (inline definition)
@@ -91,6 +93,45 @@ function appUrl(request: NextRequest, pathname: string): NextRequest['nextUrl']
   return url
 }
 
+/**
+ * Whether `pathname` is a docs page route — `/docs/<section>/<page>` or
+ * `/superadmin/docs/<section>/<page>` — whose section and page the docs
+ * registry does not have together. Segments are compared decoded, the way the
+ * page reads its params.
+ */
+function isMissingDocsPage(pathname: string): boolean {
+  const match = pathname.match(/^(\/superadmin)?\/docs\/([^/]+)\/([^/]+)$/)
+  if (!match) return false
+
+  let sectionSlug: string
+  let pageSlug: string
+  try {
+    sectionSlug = decodeURIComponent(match[2])
+    pageSlug = decodeURIComponent(match[3])
+  } catch {
+    return true
+  }
+
+  const sections = match[1] ? DOCS_REGISTRY.superadmin : DOCS_REGISTRY.public
+  return !sections.some(section => section.slug === sectionSlug && section.pages.some(page => page.slug === pageSlug))
+}
+
+/**
+ * Serve the app's not-found page with a 404 status for a docs page the
+ * registry does not have. The docs pages answer 404 on their own only where
+ * their `dynamicParams = false` has a list to check: in `next dev`, and for
+ * public docs prerendered by an app whose locale is fixed. Rendered on demand
+ * (superadmin docs always, public docs when the locale comes from the
+ * request), their notFound() runs inside the layouts' Suspense boundaries,
+ * after the response head has gone out with a 200. Deciding it here, before
+ * anything renders, gives those requests the 404.
+ */
+function rewriteToNotFound(request: NextRequest, requestHeaders: Headers): NextResponse {
+  return syncSessionHint(request, NextResponse.rewrite(appUrl(request, '/_not-found'), {
+    request: { headers: requestHeaders },
+  }))
+}
+
 /**
  * Send a visitor without a session to login. LoginForm reads `callbackUrl` and
  * returns them to the page they asked for, query included, once signed in.
@@ -178,6 +219,18 @@ function passThrough(request: NextRequest, requestHeaders: Headers): NextRespons
   }))
 }
 
+let legacyDocsAccessWarned = false
+
+/** Says once per server process what to change in an app config that still
+ * gates /docs with the older `docs.public` boolean. */
+function warnLegacyDocsAccess(docsConfig: Parameters<typeof legacyDocsAccessMessage>[0]): void {
+  if (legacyDocsAccessWarned) return
+  const message = legacyDocsAccessMessage(docsConfig)
+  if (!message) return
+  legacyDocsAccessWarned = true
+  console.warn(`[NextSpark] ${message}`)
+}
+
 export async function proxy(request: NextRequest) {
   const { pathname } = request.nextUrl
 
@@ -191,36 +244,58 @@ export async function proxy(request: NextRequest) {
     if (themeResponse) return themeResponse
   }
 
-  // 2. Redirect old docs URLs to new structure (2-level -> 3-level)
-  const oldDocsPattern = /^\/docs\/([^\/]+)\/([^\/]+)$/
-  const oldDocsMatch = pathname.match(oldDocsPattern)
-
+  // 2. Redirect historical 3-level docs URLs (/docs/<core|theme>/<section>/<page>)
+  // to the current route. That split predates this app's history: `core` and
+  // `theme` were the only two categories ever generated (a third, `plugins`,
+  // was scaffolded but never activated), and both were collapsed into a single
+  // docs tree per source - `public` (served at /docs) and `superadmin` (served
+  // at /superadmin/docs) - without renaming any section that survived the
+  // collapse. A section from that era can therefore only be in one of the two
+  // registries today, or in neither if its docs were dropped rather than
+  // moved; the redirect follows the section, not the old category. The page
+  // has to survive too - a section can live on with a different set of pages -
+  // so both are checked against the registry rather than only the section,
+  // which is the one thing this route can actually confirm still resolves.
+  const oldDocsMatch = pathname.match(/^\/docs\/(?:core|theme)\/([^/]+)\/([^/]+)$/)
   if (oldDocsMatch) {
     const [, sectionSlug, pageSlug] = oldDocsMatch
-    const themeSections = ['theme-overview', 'theme-features']
-    const category = themeSections.includes(sectionSlug) ? 'theme' : 'core'
-    const cleanSection = sectionSlug.replace(/^theme-/, '')
-
     const newUrl = request.nextUrl.clone()
-    newUrl.pathname = `/docs/${category}/${cleanSection}/${pageSlug}`
+    const superadminSection = DOCS_REGISTRY.superadmin.find((section) => section.slug === sectionSlug)
+    const publicSection = DOCS_REGISTRY.public.find((section) => section.slug === sectionSlug)
+
+    if (superadminSection?.pages.some((page) => page.slug === pageSlug)) {
+      newUrl.pathname = `/superadmin/docs/${sectionSlug}/${pageSlug}`
+    } else if (publicSection?.pages.some((page) => page.slug === pageSlug)) {
+      newUrl.pathname = `/docs/${sectionSlug}/${pageSlug}`
+    } else {
+      // The section is gone, or survived without this exact page - either way
+      // there is no page left to send this to, so it goes to the docs home
+      // instead of a dead link.
+      newUrl.pathname = '/docs'
+    }
     return NextResponse.redirect(newUrl, 301)
   }
 
-  // 3. Documentation access control
+  // 3. Documentation access control: docs.publicAccess, or the older
+  // docs.public boolean it replaced (see lib/docs/access)
   if (isUnder(pathname, '/docs')) {
-    const appConfig = getThemeAppConfig(activeTheme as string)
+    const docsConfig = getThemeAppConfig(activeTheme as string)?.docs
+    warnLegacyDocsAccess(docsConfig)
 
-    if (appConfig?.docs?.public === false) {
+    if (!isDocsPublic(docsConfig)) {
       try {
         const { data: session } = await getSession(request)
 
         if (!session) {
           return redirectToLogin(request)
         }
-      } catch (error) {
+      } catch {
         return redirectToLogin(request)
       }
     }
+    if (isMissingDocsPage(pathname)) {
+      return rewriteToNotFound(request, requestHeaders)
+    }
     return passThrough(request, requestHeaders)
   }
 
@@ -290,6 +365,10 @@ export async function proxy(request: NextRequest) {
         requestHeaders.set('x-active-team-id', activeTeamId)
       }
 
+      if (isSuperadminRoute && isMissingDocsPage(pathname)) {
+        return rewriteToNotFound(request, requestHeaders)
+      }
+
       return passThrough(request, requestHeaders)
     } catch (error) {
       console.error('Proxy error:', error)

package/templates/public/sw.js

@@ -1,10 +1,10 @@
 // Empty service worker to prevent 404 errors
 // This file exists only to stop browsers from requesting a non-existent service worker
 
-self.addEventListener('install', function(event) {
+self.addEventListener('install', function() {
   // No caching or special behavior
 });
 
-self.addEventListener('fetch', function(event) {
+self.addEventListener('fetch', function() {
   // No fetch interception
 });

package/templates/scripts/cy-run-prod.cjs

@@ -83,7 +83,7 @@ function killPort(port) {
           if (pid && /^\d+$/.test(pid)) {
             try {
               execSync(`taskkill /PID ${pid} /F`, { stdio: 'ignore' })
-            } catch (e) {
+            } catch {
               // Process might already be dead
             }
           }
@@ -92,7 +92,7 @@ function killPort(port) {
       execSync(`lsof -ti:${port} | xargs kill -9 2>/dev/null || true`, { stdio: 'ignore' })
     }
     console.log(`[cy:run:prod] Port ${port} cleared`)
-  } catch (e) {
+  } catch {
     // No process on port, that's fine
     console.log(`[cy:run:prod] Port ${port} was already free`)
   }
@@ -206,16 +206,16 @@ function cleanup(server) {
         // Kill process group
         try {
           process.kill(-server.pid, 'SIGKILL')
-        } catch (e) {
+        } catch {
           // If process group kill fails, try direct kill
           try {
             server.kill('SIGKILL')
-          } catch (e2) {
+          } catch {
             // Process might already be dead
           }
         }
       }
-    } catch (e) {
+    } catch {
       // Process might already be dead
     }
   }

package/tests/jest/__mocks__/@nextsparkjs/registries/template-registry.client.ts

@@ -0,0 +1,11 @@
+/**
+ * Mock Template Registry (client) for Jest tests
+ *
+ * No theme overrides a page in tests, so every page renders its default.
+ */
+
+import type { ComponentType } from 'react'
+
+export function getTemplateOrDefaultClient<P>(_path: string, defaultComponent: ComponentType<P>): ComponentType<P> {
+  return defaultComponent
+}

package/tests/jest/__mocks__/next-server.js

@@ -98,6 +98,16 @@ class MockNextResponse {
     return response
   }
 
+  // Serves another URL of the app in place of the requested one, with the
+  // forwarded request headers kept for assertions like next() above.
+  static rewrite(url, init = {}) {
+    const response = new MockNextResponse(null, { status: 200, headers: init.headers })
+    response.type = 'rewrite'
+    response.rewriteUrl = String(url)
+    response.requestHeaders = init.request && init.request.headers ? init.request.headers : null
+    return response
+  }
+
   static redirect(url, status = 307) {
     const response = new MockNextResponse(null, { status, headers: { Location: String(url) } })
     response.type = 'redirect'