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

package/templates/contents/themes/starter/tests/cypress/src/index.ts

@@ -85,4 +85,5 @@ export {
   loginAsViewer,
   loginAsDefaultDeveloper,
   loginAsDefaultSuperadmin,
+  hasSeededTeamRoleUser,
 } from './session-helpers'

package/templates/contents/themes/starter/tests/cypress/src/session-helpers.ts

@@ -39,19 +39,50 @@ const SUPERADMIN_PASSWORD = Cypress.env('SUPERADMIN_PASSWORD') || 'Pandora1234'
 const TEST_PASSWORD = Cypress.env('TEST_PASSWORD') || 'Test1234'
 
 /**
- * Default Theme Test Users
- * Teams: Everpoint Labs, Ironvale Global, Riverstone Ventures
+ * Team-role test users.
  *
- * Note: These are fallback demo users. For selector tests, use CORE_USER (developer).
+ * The starter seeds exactly two users (core migration 090): superadmin and
+ * developer. The names below come from the default theme's richer sample data,
+ * and every one of them has to be pointed at a real user through the matching
+ * env var before the specs that use it can run.
+ *
+ * OWNER is the exception, and it matters: it is what the CRUD specs log in as,
+ * so its fallback is the user the starter actually creates — superadmin owns
+ * the initial team. Leaving it on a name with no row made the whole UAT suite
+ * fail in session setup, before a single assertion.
  */
 export const DEFAULT_THEME_USERS = {
-  OWNER: Cypress.env('OWNER_EMAIL') || 'carlos.mendoza@nextspark.dev',
+  OWNER: Cypress.env('OWNER_EMAIL') || 'superadmin@nextspark.dev',
   ADMIN: Cypress.env('ADMIN_EMAIL') || 'james.wilson@nextspark.dev',
   MEMBER: Cypress.env('MEMBER_EMAIL') || 'emily.johnson@nextspark.dev',
   EDITOR: Cypress.env('EDITOR_EMAIL') || 'diego.ramirez@nextspark.dev',
   VIEWER: Cypress.env('VIEWER_EMAIL') || 'sarah.davis@nextspark.dev',
 } as const
 
+/**
+ * The password that goes with OWNER.
+ *
+ * OWNER falls back to the seeded superadmin, and that user's password is the
+ * superadmin one, not the demo-user one. A theme that points OWNER at a user of
+ * its own sets OWNER_EMAIL, and then the demo password is the right default.
+ */
+const OWNER_PASSWORD =
+  Cypress.env('OWNER_PASSWORD') ||
+  (Cypress.env('OWNER_EMAIL') ? TEST_PASSWORD : SUPERADMIN_PASSWORD)
+
+/**
+ * Whether a non-owner team role points at a user that exists.
+ *
+ * Only OWNER has a seeded fallback. The other four keep the default theme's
+ * names, which resolve to nothing here until the theme seeds them and sets the
+ * matching env var. A spec that needs one guards on this instead of failing in
+ * session setup, where the error is a ten-second timeout on the Dev Keyring
+ * rather than "this user does not exist".
+ */
+export function hasSeededTeamRoleUser(role: 'ADMIN' | 'MEMBER' | 'EDITOR' | 'VIEWER'): boolean {
+  return Boolean(Cypress.env(`${role}_EMAIL`))
+}
+
 /**
  * Core System Users (from core/migrations/090_sample_data.sql)
  * These users have special global roles, not team-based roles
@@ -164,7 +195,7 @@ function apiLogin(email: string, password: string = TEST_PASSWORD): Cypress.Chai
  */
 export function loginAsDefaultOwner() {
   cy.session('default-owner-session', () => {
-    apiLogin(DEFAULT_THEME_USERS.OWNER).then((apiLoginSucceeded) => {
+    apiLogin(DEFAULT_THEME_USERS.OWNER, OWNER_PASSWORD).then((apiLoginSucceeded) => {
       // If API login succeeded, we need to visit a page before setting localStorage
       if (apiLoginSucceeded) {
         cy.visit('/dashboard', { timeout: 60000 })
@@ -389,22 +420,22 @@ export function getThemeUsers() {
  */
 export const BILLING_TEAMS = {
   FREE: {
-    teamId: 'team-personal-carlos-001',
+    teamId: Cypress.env('BILLING_FREE_TEAM_ID') || 'team-personal-carlos-001',
     name: 'Carlos Personal',
     planSlug: 'free',
-    owner: 'carlos.mendoza@nextspark.dev'
+    owner: Cypress.env('BILLING_FREE_OWNER') || 'carlos.mendoza@nextspark.dev'
   },
   PRO: {
-    teamId: 'team-everpoint-001',
+    teamId: Cypress.env('BILLING_PRO_TEAM_ID') || 'team-everpoint-001',
     name: 'Everpoint Labs',
     planSlug: 'pro',
-    owner: 'carlos.mendoza@nextspark.dev'
+    owner: Cypress.env('BILLING_PRO_OWNER') || 'carlos.mendoza@nextspark.dev'
   },
   ENTERPRISE: {
-    teamId: 'team-ironvale-002',
+    teamId: Cypress.env('BILLING_ENTERPRISE_TEAM_ID') || 'team-ironvale-002',
     name: 'Ironvale Global',
     planSlug: 'enterprise',
-    owner: 'ana.garcia@nextspark.dev'
+    owner: Cypress.env('BILLING_ENTERPRISE_OWNER') || 'ana.garcia@nextspark.dev'
   }
 } as const
 

package/templates/contents/themes/starter/tests/cypress/support/commands.ts

@@ -140,18 +140,37 @@ Cypress.Commands.add('logout', () => {
 })
 
 /**
- * Create a task via API
+ * The headers an entity API call needs, `x-team-id` included.
+ *
+ * The app writes `activeTeamId` into localStorage while the dashboard loads, so
+ * a command that runs before any dashboard visit — a `beforeEach` seeding data,
+ * typically — finds nothing there. Without the header the API answers 400
+ * TEAM_CONTEXT_REQUIRED, and since these requests do not fail on status the
+ * seed silently does nothing: the failure only surfaces later, as an assertion
+ * about data that was never created. Asking the API for the team is what makes
+ * the command work from any starting point.
  */
-Cypress.Commands.add('createTask', (data) => {
+function apiHeaders(): Cypress.Chainable<Record<string, string>> {
+  const base: Record<string, string> = { 'Content-Type': 'application/json' }
+
   return cy.window().then((win) => {
-    const teamId = win.localStorage.getItem('activeTeamId')
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    }
-    if (teamId) {
-      headers['x-team-id'] = teamId
-    }
+    const stored = win.localStorage.getItem('activeTeamId')
+    if (stored) return cy.wrap({ ...base, 'x-team-id': stored })
+
+    return cy
+      .request({ method: 'GET', url: '/api/v1/teams', failOnStatusCode: false })
+      .then((response) => {
+        const teamId = response.body?.data?.[0]?.id
+        return cy.wrap(teamId ? { ...base, 'x-team-id': teamId } : base)
+      })
+  })
+}
 
+/**
+ * Create a task via API
+ */
+Cypress.Commands.add('createTask', (data) => {
+  return apiHeaders().then((headers) => {
     return cy.request({
       method: 'POST',
       url: '/api/v1/tasks',
@@ -171,15 +190,7 @@ Cypress.Commands.add('createTask', (data) => {
  * Delete a task via API
  */
 Cypress.Commands.add('deleteTask', (id: string) => {
-  return cy.window().then((win) => {
-    const teamId = win.localStorage.getItem('activeTeamId')
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    }
-    if (teamId) {
-      headers['x-team-id'] = teamId
-    }
-
+  return apiHeaders().then((headers) => {
     return cy.request({
       method: 'DELETE',
       url: `/api/v1/tasks/${id}`,

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

@@ -1,6 +1,7 @@
 import React from 'react'
 import { cn } from '@nextsparkjs/core/lib/utils'
 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'
 
@@ -171,7 +172,7 @@ export function PostContentBlock({
             // Em/italic
             'prose-em:italic'
           )}
-          dangerouslySetInnerHTML={{ __html: content }}
+          dangerouslySetInnerHTML={{ __html: sanitizeBlockHtml(content) }}
         />
 
         {/* Optional Divider after content */}
@@ -195,3 +196,6 @@ export function PostContentBlock({
     </section>
   )
 }
+
+// The generated block registry imports this as the module's default.
+export default PostContentBlock

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

@@ -41,6 +41,6 @@ export const postContentSpecificSchema = z.object({
  * Complete Post Content Block Schema
  * Note: postContentSpecificSchema.content overrides baseBlockSchema.content
  */
-export const schema = baseBlockSchema.merge(postContentSpecificSchema)
+export const schema = baseBlockSchema.extend(postContentSpecificSchema.shape)
 
 export type PostContentBlockProps = z.infer<typeof schema>

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

@@ -113,3 +113,6 @@ export function HeroBlock({
     </section>
   )
 }
+
+// The generated block registry imports this as the module's default.
+export default HeroBlock

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

@@ -27,7 +27,7 @@ export const heroSpecificSchema = z.object({
  * Complete Hero Block Schema
  * Combines base fields + hero-specific fields
  */
-export const schema = baseBlockSchema.merge(heroSpecificSchema)
+export const schema = baseBlockSchema.extend(heroSpecificSchema.shape)
 
 export type HeroBlockProps = z.infer<typeof schema>
 

package/templates/proxy.ts

@@ -1,4 +1,10 @@
 /**
+ * @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 Proxy (Next.js 16+)
  *
  * Handles authentication, route protection, and user context injection.
@@ -7,8 +13,8 @@
  * Key responsibilities:
  * 1. Theme middleware override support
  * 2. Documentation access control
- * 3. Protected route authentication
- * 4. User header injection for downstream use (x-user-id, x-pathname)
+ * 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)
  *
  * IMPORTANT: The EntityPermissionLayout depends on x-user-id and x-pathname
  * headers being set here for server-side permission validation.
@@ -20,6 +26,8 @@ import {
   executeThemeMiddleware,
   getThemeAppConfig
 } 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'
 
 /**
  * Session type for proxy (inline definition)
@@ -64,6 +72,53 @@ function isPublicPath(pathname: string): boolean {
   )
 }
 
+/**
+ * Whether `pathname` is `prefix` or a path under it: `/devtools/config` is,
+ * `/devtools-guide` and `/profile-photo.jpg` are not.
+ */
+function isUnder(pathname: string, prefix: string): boolean {
+  return pathname === prefix || pathname.startsWith(`${prefix}/`)
+}
+
+/**
+ * A URL on this app at `pathname`, keeping the base path and locale the request
+ * came in with; one built from `request.url` would lose both.
+ */
+function appUrl(request: NextRequest, pathname: string): NextRequest['nextUrl'] {
+  const url = request.nextUrl.clone()
+  url.pathname = pathname
+  url.search = ''
+  return url
+}
+
+/**
+ * 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.
+ */
+function redirectToLogin(request: NextRequest): NextResponse {
+  const loginUrl = appUrl(request, '/login')
+  loginUrl.searchParams.set('callbackUrl', `${request.nextUrl.pathname}${request.nextUrl.search}`)
+  return NextResponse.redirect(loginUrl)
+}
+
+/** Send a signed-in user without the role an area needs back to the dashboard. */
+function redirectAccessDenied(request: NextRequest): NextResponse {
+  const dashboardUrl = appUrl(request, '/dashboard')
+  dashboardUrl.searchParams.set('error', 'access_denied')
+  return NextResponse.redirect(dashboardUrl)
+}
+
+/**
+ * The session the request's cookies carry, asked of this app's own auth route,
+ * which is served under the base path like every other route.
+ */
+function getSession(request: NextRequest) {
+  return betterFetch<Session>('/api/auth/get-session', {
+    baseURL: `${request.nextUrl.origin}${request.nextUrl.basePath}`,
+    headers: { cookie: request.headers.get('cookie') || '' },
+  })
+}
+
 /**
  * Identity headers this proxy injects for downstream server code.
  *
@@ -74,7 +129,7 @@ function isPublicPath(pathname: string): boolean {
  * dispatches Server Actions by the `Next-Action` header, not by the URL, so an
  * action can be POSTed to a public path with a forged `x-user-id`.
  */
-const TRUSTED_IDENTITY_HEADERS = ['x-user-id', 'x-user-email', 'x-pathname'] as const
+const TRUSTED_IDENTITY_HEADERS = ['x-user-id', 'x-user-email', 'x-pathname', 'x-active-team-id'] as const
 
 /**
  * Build the request headers forwarded to the app: inbound copy minus every
@@ -89,15 +144,38 @@ function sanitizeRequestHeaders(request: NextRequest): Headers {
   return headers
 }
 
+/**
+ * Keep the readable session hint (lib/auth/session-hint) in line with the
+ * session cookie, so client code knows whether to ask for the session. A browser
+ * that got its session without client code seeing it (before the hint existed,
+ * or through OAuth) gets the hint on its next request, and one whose session
+ * cookie is gone loses it. The session itself is not checked here.
+ */
+function syncSessionHint(request: NextRequest, response: NextResponse): NextResponse {
+  const hasSession = hasSessionCookie(request.headers.get('cookie'))
+  const hinted = request.cookies.get(SESSION_HINT_COOKIE)?.value === '1'
+  if (hasSession && !hinted) {
+    response.cookies.set(SESSION_HINT_COOKIE, '1', {
+      path: '/',
+      maxAge: SESSION_HINT_MAX_AGE,
+      sameSite: 'lax',
+      secure: request.nextUrl.protocol === 'https:',
+    })
+  } else if (!hasSession && hinted) {
+    response.cookies.set(SESSION_HINT_COOKIE, '', { path: '/', maxAge: 0 })
+  }
+  return response
+}
+
 /**
  * Continue to the app with the (sanitized) request headers.
  * Every pass-through in this proxy MUST go through here so the strip applies
  * to public paths, /api/v1 and unmatched routes alike.
  */
-function passThrough(requestHeaders: Headers): NextResponse {
-  return NextResponse.next({
+function passThrough(request: NextRequest, requestHeaders: Headers): NextResponse {
+  return syncSessionHint(request, NextResponse.next({
     request: { headers: requestHeaders },
-  })
+  }))
 }
 
 export async function proxy(request: NextRequest) {
@@ -129,76 +207,71 @@ export async function proxy(request: NextRequest) {
   }
 
   // 3. Documentation access control
-  if (pathname.startsWith('/docs')) {
+  if (isUnder(pathname, '/docs')) {
     const appConfig = getThemeAppConfig(activeTheme as string)
 
     if (appConfig?.docs?.public === false) {
       try {
-        const { data: session } = await betterFetch<Session>(
-          '/api/auth/get-session',
-          {
-            baseURL: request.nextUrl.origin,
-            headers: { cookie: request.headers.get('cookie') || '' },
-          }
-        )
+        const { data: session } = await getSession(request)
 
         if (!session) {
-          const loginUrl = new URL('/login', request.url)
-          loginUrl.searchParams.set('redirect', pathname)
-          return NextResponse.redirect(loginUrl)
+          return redirectToLogin(request)
         }
       } catch (error) {
-        const loginUrl = new URL('/login', request.url)
-        loginUrl.searchParams.set('redirect', pathname)
-        return NextResponse.redirect(loginUrl)
+        return redirectToLogin(request)
       }
     }
-    return passThrough(requestHeaders)
+    return passThrough(request, requestHeaders)
   }
 
   // 4. Allow public paths
   if (isPublicPath(pathname)) {
-    return passThrough(requestHeaders)
+    return passThrough(request, requestHeaders)
   }
 
   // 5. API v1 routes handle their own dual authentication
   if (pathname.startsWith('/api/v1')) {
-    return passThrough(requestHeaders)
+    return passThrough(request, requestHeaders)
   }
 
-  // 6. Protected routes - require authentication and inject user headers
-  const isAdminRoute = pathname.startsWith('/admin')
+  // 6. Protected routes - require authentication and inject user headers.
+  // Areas are matched by path segment, so /dashboard-guide is not /dashboard.
+  // /superadmin and /devtools also need a role, the same ones SuperAdminGuard
+  // and DeveloperGuard let in. The guards decide it again in the browser, but
+  // only after the page has been served, so it is decided here first.
+  const isAdminRoute = isUnder(pathname, '/admin')
+  const isSuperadminRoute = isUnder(pathname, '/superadmin')
+  const isDevtoolsRoute = isUnder(pathname, '/devtools')
   const isProtectedRoute =
-    pathname.startsWith('/dashboard') ||
-    pathname.startsWith('/admin') ||
-    pathname.startsWith('/settings') ||
-    pathname.startsWith('/profile') ||
-    pathname.startsWith('/update-password') ||
-    isAdminRoute
+    isUnder(pathname, '/dashboard') ||
+    isUnder(pathname, '/settings') ||
+    isUnder(pathname, '/profile') ||
+    isUnder(pathname, '/update-password') ||
+    isAdminRoute ||
+    isSuperadminRoute ||
+    isDevtoolsRoute
 
   if (isProtectedRoute) {
     try {
-      const { data: session } = await betterFetch<Session>(
-        '/api/auth/get-session',
-        {
-          baseURL: request.nextUrl.origin,
-          headers: { cookie: request.headers.get('cookie') || '' },
-        }
-      )
+      const { data: session } = await getSession(request)
 
       if (!session) {
-        const loginUrl = new URL('/login', request.url)
-        loginUrl.searchParams.set('callbackUrl', pathname)
-        return NextResponse.redirect(loginUrl)
+        return redirectToLogin(request)
       }
 
+      const role = session.user?.role
+
       // Admin Panel superadmin-only check
-      if (isAdminRoute) {
-        if (!session.user?.role || session.user.role !== 'superadmin') {
-          const dashboardUrl = new URL('/dashboard', request.url)
-          dashboardUrl.searchParams.set('error', 'access_denied')
-          return NextResponse.redirect(dashboardUrl)
-        }
+      if (isAdminRoute && role !== 'superadmin') {
+        return redirectAccessDenied(request)
+      }
+
+      if (isSuperadminRoute && role !== 'superadmin' && role !== 'developer') {
+        return redirectAccessDenied(request)
+      }
+
+      if (isDevtoolsRoute && role !== 'developer') {
+        return redirectAccessDenied(request)
       }
 
       // Inject user headers for downstream use, ONLY from the verified session
@@ -210,21 +283,33 @@ export async function proxy(request: NextRequest) {
       if (session.user?.email) {
         requestHeaders.set('x-user-email', session.user.email)
       }
+      // The team this session chose, for the dashboard layouts' permission
+      // checks; a cookie another session left behind names no team here.
+      const activeTeamId = activeTeamIdForSession(request.cookies.get(ACTIVE_TEAM_COOKIE)?.value, session.session?.id)
+      if (activeTeamId) {
+        requestHeaders.set('x-active-team-id', activeTeamId)
+      }
 
-      return passThrough(requestHeaders)
+      return passThrough(request, requestHeaders)
     } catch (error) {
       console.error('Proxy error:', error)
-      const loginUrl = new URL('/login', request.url)
-      loginUrl.searchParams.set('callbackUrl', pathname)
-      return NextResponse.redirect(loginUrl)
+      return redirectToLogin(request)
     }
   }
 
-  return passThrough(requestHeaders)
+  return passThrough(request, requestHeaders)
 }
 
+/**
+ * Everything runs through the proxy except the exact paths of Next's own
+ * output: `_next/static/`, the `_next/image` endpoint and `favicon.ico`.
+ * Excluding by file extension, or by a prefix without its boundary, would let a
+ * dynamic segment such as `alice.png` or `favicon.icoevil` reach the app without
+ * the session check and with forged identity headers intact. Files under
+ * public/ simply pass through.
+ */
 export const config = {
   matcher: [
-    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+    '/((?!_next/static/|_next/image$|favicon\\.ico$).*)',
   ],
 }

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

@@ -0,0 +1,9 @@
+/**
+ * The client half of the block registry, for tests.
+ *
+ * Re-exports the mock's configs rather than restating them, so the two halves
+ * cannot drift the way the generated pair must not.
+ */
+export { BLOCK_REGISTRY, BLOCK_METADATA } from './block-registry'
+
+export const BLOCK_CATEGORIES: string[] = []

package/tests/jest/__mocks__/@nextsparkjs/registries/block-registry.lazy.ts

@@ -0,0 +1,5 @@
+/**
+ * Mock Block Registry (lazy components) for Jest tests
+ */
+
+export const BLOCK_COMPONENTS: Record<string, any> = {}

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

@@ -0,0 +1,42 @@
+/**
+ * Mock Icon Registry for Jest tests
+ *
+ * Holds the real lucide components, not stand-ins: serialization resolves an
+ * icon's registry name by identity, so a config's `icon: CheckSquare` only
+ * round-trips when the registry holds that same component.
+ */
+import type { LucideIcon } from 'lucide-react'
+import {
+  Box,
+  CheckSquare,
+  Circle,
+  FileText,
+  Folder,
+  Home,
+  LayoutGrid,
+  Newspaper,
+  Search,
+  Settings,
+  Users
+} from 'lucide-react'
+
+export const ICON_REGISTRY: Record<string, LucideIcon> = {
+  Box,
+  CheckSquare,
+  Circle,
+  FileText,
+  Folder,
+  Home,
+  LayoutGrid,
+  Newspaper,
+  Search,
+  Settings,
+  Users
+}
+
+export type IconName = keyof typeof ICON_REGISTRY
+
+export const ICON_METADATA = {
+  totalIcons: Object.keys(ICON_REGISTRY).length,
+  generatedAt: new Date().toISOString()
+}

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

@@ -3,8 +3,10 @@
  *
  * Loads the corresponding `messages/<locale>/<root>.json` file directly and
  * resolves keys inside `namespace` (which can be dotted, e.g. `email.verifyEmail`).
- * Supports ICU-style `{var}` placeholders in values — replaced naively, no
- * pluralization. Sufficient for email template snapshot tests.
+ * Supports ICU-style `{var}` placeholders, replaced naively, plus the `plural`
+ * argument type (`{var, plural, one {...} other {...}}`) resolved through
+ * `Intl.PluralRules` — the subset the email templates actually use. Sufficient
+ * for email template snapshot tests, not a general ICU MessageFormat parser.
  */
 
 const path = require('path')
@@ -28,9 +30,87 @@ function loadNamespace(locale, namespace) {
   return obj
 }
 
-function format(template, params) {
+/**
+ * Resolves every `{varName, plural, category {text} ...}` block in `template`,
+ * picking the branch via `Intl.PluralRules` (falling back to an explicit
+ * `=<n>` match, then to `other`) and substituting `#` with the value.
+ * Parses by brace-depth rather than regex so a category's text may itself
+ * contain other `{placeholder}` tokens.
+ */
+function resolveIcuPlural(template, params, locale) {
+  const marker = ', plural,'
+  let result = ''
+  let i = 0
+
+  while (i < template.length) {
+    if (template[i] !== '{') {
+      result += template[i]
+      i++
+      continue
+    }
+
+    const commaIndex = template.indexOf(',', i)
+    if (commaIndex === -1 || template.slice(commaIndex, commaIndex + marker.length) !== marker) {
+      result += template[i]
+      i++
+      continue
+    }
+
+    const varName = template.slice(i + 1, commaIndex).trim()
+    let cursor = commaIndex + marker.length
+    const categories = {}
+
+    while (cursor < template.length) {
+      while (/\s/.test(template[cursor])) cursor++
+      if (template[cursor] === '}') {
+        cursor++
+        break
+      }
+      const catStart = cursor
+      while (template[cursor] !== '{') cursor++
+      const catName = template.slice(catStart, cursor).trim()
+      cursor++ // skip the category's opening '{'
+      let subDepth = 1
+      const subStart = cursor
+      while (subDepth > 0) {
+        if (template[cursor] === '{') subDepth++
+        else if (template[cursor] === '}') subDepth--
+        if (subDepth > 0) cursor++
+      }
+      categories[catName] = template.slice(subStart, cursor)
+      cursor++ // skip the category's closing '}'
+      while (/\s/.test(template[cursor])) cursor++
+      if (template[cursor] === '}') {
+        cursor++
+        break
+      }
+    }
+
+    const value = params ? params[varName] : undefined
+    const numValue = Number(value)
+    let category = categories[`=${numValue}`] !== undefined ? `=${numValue}` : undefined
+    if (category === undefined) {
+      try {
+        category = new Intl.PluralRules(locale || 'en').select(numValue)
+      } catch {
+        category = 'other'
+      }
+      if (categories[category] === undefined) category = 'other'
+    }
+
+    result += (categories[category] ?? '').replace(/#/g, String(numValue))
+    i = cursor
+  }
+
+  return result
+}
+
+function format(template, params, locale) {
   if (!params) return template
-  return template.replace(/\{(\w+)\}/g, (_, key) =>
+  const resolved = template.includes(', plural,')
+    ? resolveIcuPlural(template, params, locale)
+    : template
+  return resolved.replace(/\{(\w+)\}/g, (_, key) =>
     params[key] === undefined ? `{${key}}` : String(params[key]),
   )
 }
@@ -45,7 +125,7 @@ async function getTranslations(opts) {
     if (value === undefined) {
       throw new Error(`next-intl mock: missing key "${key}" in namespace "${namespace}"`)
     }
-    return format(value, params)
+    return format(value, params, locale)
   }
 }