@nextsparkjs/core 0.1.0-beta.176 → 0.1.0-beta.178

package/dist/templates/app/(auth)/login/page.tsx

@@ -2,6 +2,8 @@ import type { Metadata } from 'next'
 import { LoginForm } from '@nextsparkjs/core/components/auth/forms/LoginForm'
 import { getTemplateOrDefault, getMetadataOrDefault } from '@nextsparkjs/core/lib/template-resolver'
 
+export const dynamic = 'force-dynamic'
+
 const defaultMetadata: Metadata = {
   title: 'Sign In',
   description: 'Sign in to your account to access the platform',

package/dist/templates/app/(auth)/signup/page.tsx

@@ -6,6 +6,10 @@ import { getTemplateOrDefault, getMetadataOrDefault } from '@nextsparkjs/core/li
 import { AUTH_CONFIG } from '@nextsparkjs/core/lib/config'
 import { TeamService } from '@nextsparkjs/core/lib/services'
 
+// This page reads DB state (TeamService.hasGlobal) and redirect()s during render,
+// so it must render per-request and never be statically prerendered at build time.
+export const dynamic = 'force-dynamic'
+
 const defaultMetadata: Metadata = {
   title: 'Create Account',
   description: 'Create your account to start using our platform',

package/dist/templates/app/superadmin/team-roles/page.tsx

@@ -40,7 +40,7 @@ import { getTemplateOrDefaultClient } from "@nextsparkjs/registries/template-reg
  * Both use pre-computed data for O(1) runtime lookups.
  */
 function TeamRolesPage() {
-  const teamRolesConfig = APP_CONFIG_MERGED.teamRoles;
+  const teamRolesConfig = APP_CONFIG_MERGED.teams.roles;
   const roles = teamRolesConfig.availableTeamRoles;
   const hierarchy = teamRolesConfig.hierarchy;
 
@@ -258,7 +258,7 @@ function TeamRolesPage() {
                 <p>
                   <strong>Roles config:</strong>{" "}
                   <code className="bg-background px-1 rounded">
-                    APP_CONFIG_MERGED.teamRoles
+                    APP_CONFIG_MERGED.teams.roles
                   </code>
                 </p>
                 <p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/core",
-  "version": "0.1.0-beta.176",
+  "version": "0.1.0-beta.178",
   "description": "NextSpark - The complete SaaS framework for Next.js",
   "license": "MIT",
   "author": "NextSpark <hello@nextspark.dev>",
@@ -449,6 +449,7 @@
     "fs-extra": "^11.2.0",
     "gray-matter": "^4.0.3",
     "lucide-react": "^0.539.0",
+    "mermaid": "^11.0.0",
     "next-intl": "^4.9.1",
     "next-themes": "^0.4.6",
     "ora": "^8.1.1",
@@ -469,7 +470,7 @@
     "tailwind-merge": "^3.3.1",
     "uuid": "^13.0.0",
     "zod": "^4.1.5",
-    "@nextsparkjs/testing": "0.1.0-beta.176"
+    "@nextsparkjs/testing": "0.1.0-beta.178"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs || true",

package/scripts/build/registry/__tests__/team-roles.test.mjs

@@ -0,0 +1,192 @@
+/**
+ * Tests for the declarative team-role model at the build layer.
+ *
+ * Model: `teams.roles` (app.config) is the AUTHORITATIVE, declarative set of NON-OWNER
+ * roles. When present it REPLACES the defaults; when absent the set is base roles +
+ * theme custom roles (permissions.config). 'owner' is ALWAYS force-included.
+ *
+ * Covers the real production code paths:
+ *  - computeTeamRoleConfig() : the pure build-time role-set computation
+ *  - parseTeamRolesFromAppConfig() : the app.config.ts teams.roles parser
+ *  - generatePermissionsRegistry() : asserts the EMITTED literals
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/team-roles.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { computeTeamRoleConfig, generatePermissionsRegistry } from '../generators/permissions-registry.mjs'
+import { parseTeamRolesFromAppConfig } from '../discovery/permissions.mjs'
+
+// ---------------------------------------------------------------------------
+// computeTeamRoleConfig — the pure build-time computation
+// ---------------------------------------------------------------------------
+
+test('no config → default = base non-owner roles + owner (no regression)', () => {
+  const r = computeTeamRoleConfig({})
+  assert.deepEqual(r.availableRoles, ['owner', 'admin', 'member', 'viewer'])
+  assert.equal(r.defaultTeamRole, 'member')
+  assert.equal(r.customRolesCount, 0)
+  assert.deepEqual(r.coreTeamRoles, ['owner'])
+  assert.equal(r.hierarchy.owner, 100)
+})
+
+test('no teamRoles override → base + permissions.config custom roles (default theme shape)', () => {
+  const r = computeTeamRoleConfig({
+    rolesConfig: { additionalRoles: ['editor'], hierarchy: { editor: 40 } },
+  })
+  assert.deepEqual(r.availableRoles, ['owner', 'admin', 'member', 'viewer', 'editor'])
+  assert.equal(r.hierarchy.editor, 40)
+  assert.equal(r.customRolesCount, 1)
+  assert.equal(r.defaultTeamRole, 'member')
+})
+
+test('teamRoles REPLACES the whole set (owner forced, everything else dropped)', () => {
+  const r = computeTeamRoleConfig({
+    rolesConfig: { additionalRoles: ['editor'] }, // defined but NOT selected → excluded
+    teamRolesConfig: { teamRoles: ['test1', 'test2'] },
+  })
+  assert.deepEqual(r.availableRoles, ['owner', 'test1', 'test2'])
+  assert.equal(r.availableRoles.includes('admin'), false)
+  assert.equal(r.availableRoles.includes('member'), false)
+  assert.equal(r.availableRoles.includes('viewer'), false)
+  assert.equal(r.availableRoles.includes('editor'), false)
+  // default falls back to first non-owner since 'member' is not in the set
+  assert.equal(r.defaultTeamRole, 'test1')
+})
+
+test("'owner' is ALWAYS present and force-deduped", () => {
+  assert.deepEqual(computeTeamRoleConfig({ teamRolesConfig: { teamRoles: ['admin'] } }).availableRoles, ['owner', 'admin'])
+  assert.deepEqual(computeTeamRoleConfig({ teamRolesConfig: { teamRoles: ['owner', 'admin'] } }).availableRoles, ['owner', 'admin'])
+})
+
+test('empty teamRoles → owner-only team', () => {
+  const r = computeTeamRoleConfig({ teamRolesConfig: { teamRoles: [] } })
+  assert.deepEqual(r.availableRoles, ['owner'])
+  assert.equal(r.defaultTeamRole, 'owner')
+})
+
+test('selected custom role keeps its permissions.config metadata', () => {
+  const r = computeTeamRoleConfig({
+    rolesConfig: { additionalRoles: ['editor'], hierarchy: { editor: 40 }, displayNames: { editor: 'common.teamRoles.editor' } },
+    teamRolesConfig: { teamRoles: ['admin', 'editor'] },
+  })
+  assert.deepEqual(r.availableRoles, ['owner', 'admin', 'editor'])
+  assert.equal(r.hierarchy.editor, 40)
+  assert.equal(r.displayNames.editor, 'common.teamRoles.editor')
+})
+
+test('Campus-style: select admin + teacher + coach (drop member/viewer)', () => {
+  const r = computeTeamRoleConfig({
+    rolesConfig: { additionalRoles: ['teacher', 'coach'], hierarchy: { teacher: 30, coach: 20 } },
+    teamRolesConfig: { teamRoles: ['admin', 'teacher', 'coach'], defaultTeamRole: 'coach' },
+  })
+  assert.deepEqual(r.availableRoles, ['owner', 'admin', 'teacher', 'coach'])
+  assert.equal(r.defaultTeamRole, 'coach')
+  assert.equal(r.hierarchy.teacher, 30)
+})
+
+test('explicit defaultTeamRole outside the set falls back to a valid role', () => {
+  const r = computeTeamRoleConfig({ teamRolesConfig: { teamRoles: ['admin', 'lead'], defaultTeamRole: 'ghost' } })
+  assert.equal(r.availableRoles.includes('ghost'), false)
+  assert.ok(r.availableRoles.includes(r.defaultTeamRole))
+})
+
+test('non-owner hierarchy is capped below 100; owner pinned at 100', () => {
+  const r = computeTeamRoleConfig({
+    rolesConfig: { additionalRoles: ['big'], hierarchy: { big: 250 } },
+    teamRolesConfig: { teamRoles: ['big'] },
+  })
+  assert.equal(r.hierarchy.big, 99)
+  assert.equal(r.hierarchy.owner, 100)
+})
+
+// ---------------------------------------------------------------------------
+// parseTeamRolesFromAppConfig — the app.config.ts parser
+// ---------------------------------------------------------------------------
+
+test('teams.roles array form → authoritative teamRoles set', () => {
+  const parsed = parseTeamRolesFromAppConfig(`teams: { mode: 'multi-tenant', roles: ['admin', 'editor'] }`)
+  assert.deepEqual(parsed, { teamRoles: ['admin', 'editor'] })
+})
+
+test('teams.roles array form strips owner (always forced by the generator)', () => {
+  const parsed = parseTeamRolesFromAppConfig(`teams: { roles: ['owner', 'admin'] }`)
+  assert.deepEqual(parsed, { teamRoles: ['admin'] })
+})
+
+test('teams.roles array form + sibling defaultTeamRole (Campus shape, options nested)', () => {
+  const content = `
+  teams: {
+    mode: 'multi-tenant' as const,
+    options: {
+      maxMembersPerTeam: 100000,
+      allowLeaveTeam: false,
+      allowCreateTeams: false,
+    },
+    roles: ['admin', 'teacher', 'coach', 'student'],
+    defaultTeamRole: 'student',
+  },`
+  const parsed = parseTeamRolesFromAppConfig(content)
+  assert.deepEqual(parsed.teamRoles, ['admin', 'teacher', 'coach', 'student'])
+  assert.equal(parsed.defaultTeamRole, 'student')
+})
+
+test('teams without a roles key → null (generator uses the default set)', () => {
+  const content = `
+  teams: {
+    mode: 'multi-tenant' as const,
+    options: { maxMembersPerTeam: 50 },
+  },`
+  assert.equal(parseTeamRolesFromAppConfig(content), null)
+})
+
+test('a teams.availableTeamRoles sibling (not teams.roles) does NOT match (case-sensitive)', () => {
+  const content = `
+  teams: {
+    mode: 'multi-tenant',
+    availableTeamRoles: ['owner', 'admin', 'teacher'],
+  },`
+  assert.equal(parseTeamRolesFromAppConfig(content), null)
+})
+
+test('teams.roles object form parses the set + defaultTeamRole', () => {
+  const content = `
+  teams: {
+    mode: 'multi-tenant',
+    roles: {
+      availableTeamRoles: ['admin', 'editor'],
+      defaultTeamRole: 'editor',
+    },
+  },`
+  const parsed = parseTeamRolesFromAppConfig(content)
+  assert.deepEqual(parsed.teamRoles, ['admin', 'editor'])
+  assert.equal(parsed.defaultTeamRole, 'editor')
+})
+
+// ---------------------------------------------------------------------------
+// generatePermissionsRegistry — assert the EMITTED literals (the real output)
+// ---------------------------------------------------------------------------
+
+const readRoles = (out) => JSON.parse(out.match(/export const AVAILABLE_ROLES: readonly string\[\] = (\[[^\]]*\])/)[1])
+
+test('generated registry: teamRoles REPLACES the set', async () => {
+  const out = await generatePermissionsRegistry(
+    { themeName: 'test', importPath: 'x', entities: {}, teams: [], features: [],
+      roles: { additionalRoles: ['editor'] }, teamRoles: { teamRoles: ['test1', 'test2'] } },
+    [], { outputDir: '/tmp/nextspark-test', isNpmMode: false },
+  )
+  assert.deepEqual(readRoles(out), ['owner', 'test1', 'test2'])
+  assert.match(out, /export const DEFAULT_TEAM_ROLE: string = "test1"/)
+})
+
+test('generated registry: no teamRoles → base + custom (no regression)', async () => {
+  const out = await generatePermissionsRegistry(
+    { themeName: 'test', importPath: 'x', entities: {}, teams: [], features: [],
+      roles: { additionalRoles: ['editor'] }, teamRoles: null },
+    [], { outputDir: '/tmp/nextspark-test', isNpmMode: false },
+  )
+  assert.deepEqual(readRoles(out), ['owner', 'admin', 'member', 'viewer', 'editor'])
+  assert.match(out, /export const DEFAULT_TEAM_ROLE: string = "member"/)
+})

package/scripts/build/registry/discovery/permissions.mjs

@@ -223,6 +223,154 @@ function parseActionArrayFromConfig(content, sectionName) {
   return results
 }
 
+function parseStringArrayFromBlock(content, key) {
+  const match = content.match(new RegExp(`${key}:\\s*\\[([^\\]]*)\\]`))
+  if (!match) return null
+
+  return match[1]
+    .split(',')
+    .map((value) => value.trim().replace(/['"]/g, '').replace(/\s+as\s+const/g, ''))
+    .filter(Boolean)
+}
+
+function parseNumberMapFromBlock(content, key) {
+  const match = content.match(new RegExp(`${key}:\\s*\\{([^}]*)\\}`))
+  if (!match) return null
+
+  const result = {}
+  const pairs = match[1].match(/['"]?([\w-]+)['"]?:\s*(\d+)/g)
+  if (!pairs) return null
+
+  for (const pair of pairs) {
+    const pairMatch = pair.match(/['"]?([\w-]+)['"]?:\s*(\d+)/)
+    if (!pairMatch) continue
+    result[pairMatch[1]] = parseInt(pairMatch[2], 10)
+  }
+
+  return Object.keys(result).length > 0 ? result : null
+}
+
+function parseStringMapFromBlock(content, key) {
+  const match = content.match(new RegExp(`${key}:\\s*\\{([^}]*)\\}`))
+  if (!match) return null
+
+  const result = {}
+  const pairs = match[1].match(/['"]?([\w-]+)['"]?:\s*['"]([^'"]+)['"]/g)
+  if (!pairs) return null
+
+  for (const pair of pairs) {
+    const pairMatch = pair.match(/['"]?([\w-]+)['"]?:\s*['"]([^'"]+)['"]/)
+    if (!pairMatch) continue
+    result[pairMatch[1]] = pairMatch[2]
+  }
+
+  return Object.keys(result).length > 0 ? result : null
+}
+
+/**
+ * Extract the inner text of a brace-delimited object for a given key.
+ * Brace-matches so nested objects (e.g. `options: { ... }`) are handled correctly.
+ *
+ * @param {string} content - Source text
+ * @param {string} key - Object key to locate (e.g. 'teams', 'roles')
+ * @returns {string|null} The text between the matching braces, or null if not found
+ */
+function extractObjectBlock(content, key) {
+  const keyIndex = content.search(new RegExp(`\\b${key}:`))
+  if (keyIndex === -1) return null
+
+  const objectStart = content.indexOf('{', keyIndex)
+  if (objectStart === -1) return null
+
+  let depth = 0
+  for (let i = objectStart; i < content.length; i++) {
+    const ch = content[i]
+    if (ch === '{') depth += 1
+    else if (ch === '}') {
+      depth -= 1
+      if (depth === 0) return content.slice(objectStart + 1, i)
+    }
+  }
+
+  return null
+}
+
+/**
+ * Parse team roles from app.config.ts.
+ *
+ * Team roles are declared INSIDE the `teams` block (REPLACE model). `teams.roles`
+ * is the AUTHORITATIVE, declarative set of NON-OWNER team roles. 'owner' is always
+ * force-included by the generator and is stripped here if listed.
+ *
+ *   Array form (preferred) — exactly these roles (+ owner):
+ *     teams: {
+ *       mode: 'multi-tenant',
+ *       roles: ['admin', 'member', 'viewer'],
+ *       defaultTeamRole?: 'member',
+ *     }
+ *
+ *   Object form (optional inline metadata):
+ *     teams: {
+ *       roles: {
+ *         roles: [...] | availableTeamRoles: [...],  // the authoritative non-owner set
+ *         defaultTeamRole?: string,
+ *         hierarchy?: Record<string, number>,
+ *         displayNames?: Record<string, string>,
+ *         descriptions?: Record<string, string>,
+ *       },
+ *     }
+ *
+ * When `teams.roles` is ABSENT, the generator uses the default set: base roles
+ * (owner/admin/member/viewer) + theme custom roles from permissions.config.
+ *
+ * @param {string} content - app.config.ts content
+ * @returns {Object|null} Parsed team roles config ({ teamRoles?, defaultTeamRole?, ... })
+ */
+export function parseTeamRolesFromAppConfig(content) {
+  const teamsBlock = extractObjectBlock(content, 'teams')
+  if (!teamsBlock) return null
+
+  const result = {}
+
+  // Array form: teams.roles is the authoritative non-owner set ('owner' is forced).
+  const arrayRoles = parseStringArrayFromBlock(teamsBlock, 'roles')
+  if (arrayRoles) {
+    result.teamRoles = Array.from(
+      new Set(arrayRoles.filter((role) => role && role !== 'owner'))
+    )
+    const defaultMatch = teamsBlock.match(/defaultTeamRole:\s*['"]([^'"]+)['"]/)
+    if (defaultMatch) result.defaultTeamRole = defaultMatch[1]
+    return Object.keys(result).length > 0 ? result : null
+  }
+
+  // Object form: teams.roles = { roles | availableTeamRoles: [...], defaultTeamRole?, ... }
+  const rolesBlock = extractObjectBlock(teamsBlock, 'roles')
+  if (rolesBlock) {
+    const roleSet =
+      parseStringArrayFromBlock(rolesBlock, 'roles') ??
+      parseStringArrayFromBlock(rolesBlock, 'availableTeamRoles')
+    if (roleSet) {
+      result.teamRoles = Array.from(
+        new Set(roleSet.filter((role) => role && role !== 'owner'))
+      )
+    }
+
+    const defaultMatch = rolesBlock.match(/defaultTeamRole:\s*['"]([^'"]+)['"]/)
+    if (defaultMatch) result.defaultTeamRole = defaultMatch[1]
+
+    const hierarchy = parseNumberMapFromBlock(rolesBlock, 'hierarchy')
+    if (hierarchy) result.hierarchy = hierarchy
+    const displayNames = parseStringMapFromBlock(rolesBlock, 'displayNames')
+    if (displayNames) result.displayNames = displayNames
+    const descriptions = parseStringMapFromBlock(rolesBlock, 'descriptions')
+    if (descriptions) result.descriptions = descriptions
+
+    return Object.keys(result).length > 0 ? result : null
+  }
+
+  return null
+}
+
 /**
  * Discover permissions configuration from active theme
  * Returns null if theme doesn't have a permissions.config.ts
@@ -250,6 +398,7 @@ export async function discoverPermissionsConfig(config = DEFAULT_CONFIG) {
   let roles = null
   let teams = []
   let features = []
+  let teamRoles = null
   try {
     const content = readFileSync(permissionsPath, 'utf8')
     entities = parseEntitiesFromConfig(content)
@@ -271,6 +420,18 @@ export async function discoverPermissionsConfig(config = DEFAULT_CONFIG) {
     if (roles && roles.additionalRoles) {
       log(`  👥 Parsed ${roles.additionalRoles.length} custom roles: ${roles.additionalRoles.join(', ')}`, 'info')
     }
+
+    const appConfigPath = join(config.themesDir, themeName, 'config', 'app.config.ts')
+    if (existsSync(appConfigPath)) {
+      const appConfigContent = readFileSync(appConfigPath, 'utf8')
+      teamRoles = parseTeamRolesFromAppConfig(appConfigContent)
+
+      if (teamRoles) {
+        const declared = teamRoles.teamRoles?.length
+        const detail = typeof declared === 'number' ? ` (${declared} roles declared)` : ''
+        log(`  🧩 Parsed teamRoles from app.config.ts${detail}`, 'info')
+      }
+    }
   } catch (err) {
     log(`Error parsing permissions.config.ts: ${err.message}`, 'warning')
   }
@@ -282,6 +443,7 @@ export async function discoverPermissionsConfig(config = DEFAULT_CONFIG) {
     entities,
     roles,
     teams,
-    features
+    features,
+    teamRoles,
   }
 }

package/scripts/build/registry/generators/permissions-registry.mjs

@@ -19,6 +19,83 @@ const rootDir = join(__dirname, '../../../../../..')
 
 import { convertCorePath } from '../config.mjs'
 
+const BASE_TEAM_ROLES = ['owner', 'admin', 'member', 'viewer']
+const NON_REMOVABLE_TEAM_ROLES = ['owner'] // The only core team role; never removable
+const BASE_TEAM_ROLE_HIERARCHY = { owner: 100, admin: 50, member: 10, viewer: 1 }
+const BASE_TEAM_ROLE_DISPLAY_NAMES = {
+  owner: 'common.teamRoles.owner',
+  admin: 'common.teamRoles.admin',
+  member: 'common.teamRoles.member',
+  viewer: 'common.teamRoles.viewer',
+}
+const BASE_TEAM_ROLE_DESCRIPTIONS = {
+  owner: 'Full team control, cannot be removed',
+  admin: 'Manage team members and settings',
+  member: 'Standard team access',
+  viewer: 'Read-only access to team resources',
+}
+
+/**
+ * Compute the effective team-role configuration at build time.
+ *
+ * Pure (no I/O) so it can be unit-tested directly and emitted as literals.
+ * Doctrine: `teamRoles` (app.config) is the AUTHORITATIVE, declarative set of
+ * non-owner roles. When provided it REPLACES the defaults; when absent the set is
+ * the base roles + theme custom roles (permissions.config). 'owner' is ALWAYS
+ * force-included and can never be removed. Hierarchy/displayNames/descriptions are
+ * merged (base <- permissions.config <- app.config) and restricted to the effective
+ * set; the default role can never resolve to a role outside the set.
+ *
+ * @param {{ rolesConfig?: object|null, teamRolesConfig?: object|null }} opts
+ * @returns {{ coreTeamRoles: string[], availableRoles: string[], hierarchy: Record<string,number>, displayNames: Record<string,string>, descriptions: Record<string,string>, defaultTeamRole: string, customRolesCount: number }}
+ */
+export function computeTeamRoleConfig({ rolesConfig = null, teamRolesConfig = null } = {}) {
+  const legacyAdditionalRoles = Array.isArray(rolesConfig?.additionalRoles) ? rolesConfig.additionalRoles : []
+  // `teamRoles` (app.config) is the AUTHORITATIVE, declarative non-owner set when present.
+  // When absent, the default set is the base non-owner roles + theme custom roles
+  // (permissions.config.additionalRoles). Either way 'owner' is always force-included.
+  const declaredSet = Array.isArray(teamRolesConfig?.teamRoles) ? teamRolesConfig.teamRoles : null
+  const source = declaredSet ?? [...BASE_TEAM_ROLES.filter((role) => role !== 'owner'), ...legacyAdditionalRoles]
+
+  const nonOwner = []
+  for (const role of source) {
+    if (role && role !== 'owner' && !nonOwner.includes(role)) nonOwner.push(role)
+  }
+  const availableRoles = ['owner', ...nonOwner]
+
+  // hierarchy: base <- permissions.config <- app.config teamRoles; owner pinned at 100
+  const hierarchy = {
+    ...BASE_TEAM_ROLE_HIERARCHY,
+    ...(rolesConfig?.hierarchy ?? {}),
+    ...(teamRolesConfig?.hierarchy ?? {}),
+  }
+  hierarchy.owner = 100
+  for (const role of availableRoles) {
+    if (!(role in hierarchy)) hierarchy[role] = 1
+    if (role !== 'owner' && hierarchy[role] >= 100) hierarchy[role] = 99
+  }
+
+  const displayNames = { ...BASE_TEAM_ROLE_DISPLAY_NAMES, ...(rolesConfig?.displayNames ?? {}), ...(teamRolesConfig?.displayNames ?? {}) }
+  const descriptions = { ...BASE_TEAM_ROLE_DESCRIPTIONS, ...(rolesConfig?.descriptions ?? {}), ...(teamRolesConfig?.descriptions ?? {}) }
+
+  const onlyAvailable = (obj) => Object.fromEntries(Object.entries(obj).filter(([role]) => availableRoles.includes(role)))
+
+  const configuredDefault = teamRolesConfig?.defaultTeamRole
+  const defaultTeamRole = (typeof configuredDefault === 'string' && availableRoles.includes(configuredDefault))
+    ? configuredDefault
+    : (availableRoles.includes('member') ? 'member' : (availableRoles.find((role) => role !== 'owner') ?? 'owner'))
+
+  return {
+    coreTeamRoles: [...NON_REMOVABLE_TEAM_ROLES],
+    availableRoles,
+    hierarchy: onlyAvailable(hierarchy),
+    displayNames: onlyAvailable(displayNames),
+    descriptions: onlyAvailable(descriptions),
+    defaultTeamRole,
+    customRolesCount: availableRoles.filter((role) => !BASE_TEAM_ROLES.includes(role)).length,
+  }
+}
+
 /**
  * Generate pre-computed permissions registry
  * Merges core permissions + theme permissions + entity permissions at build time
@@ -187,13 +264,16 @@ export async function generatePermissionsRegistry(permissionsConfig, entities, c
 
   // Extract roles configuration
   const rolesConfig = hasThemeConfig && permissionsConfig.roles ? permissionsConfig.roles : null
+  const teamRolesConfig = hasThemeConfig && permissionsConfig.teamRoles ? permissionsConfig.teamRoles : null
+
+  // Effective team-role set, computed once at build time (base + extras − removals; owner kept)
+  const teamRoleConfig = computeTeamRoleConfig({ rolesConfig, teamRolesConfig })
 
   // Build imports (convert @/core/ paths based on NPM mode)
   const outputFilePath = join(config.outputDir, 'permissions-registry.ts')
 
   const imports = [
     `import { CORE_PERMISSIONS_CONFIG } from '${convertCorePath('@/core/lib/permissions/system', outputFilePath, config)}'`,
-    `import { APP_CONFIG_MERGED } from '${convertCorePath('@/core/lib/config/config-sync', outputFilePath, config)}'`
   ]
 
   if (hasThemeConfig) {
@@ -242,6 +322,9 @@ const FEATURE_PERMISSIONS = ${JSON.stringify(featurePermissions, null, 2)} as un
 /** Custom roles defined in permissions.config.ts */
 export const CUSTOM_ROLES: RolesConfig = ${rolesConfig ? JSON.stringify(rolesConfig, null, 2) : '{}'}
 
+/** Default role assigned to new team members (never resolves to a removed role) */
+export const DEFAULT_TEAM_ROLE: string = ${JSON.stringify(teamRoleConfig.defaultTeamRole)}
+
 // ============================================================================
 // TEAM PERMISSIONS EXPORTS
 // ============================================================================
@@ -262,44 +345,21 @@ export const TEAM_PERMISSIONS_BY_ROLE: Record<string, string[]> = (() => {
 })()
 
 // ============================================================================
-// RUNTIME MERGED PERMISSIONS (computed once on module load)
+// TEAM ROLES (effective set, computed at build time)
+// base roles + theme extras − theme removals; 'owner' is the only non-removable core role
 // ============================================================================
 
-// Core team roles
-const CORE_TEAM_ROLES = ['owner', 'admin', 'member', 'viewer'] as const
+/** Effective team roles (base + extras − removals; 'owner' always present) */
+export const AVAILABLE_ROLES: readonly string[] = ${JSON.stringify(teamRoleConfig.availableRoles)}
 
-// Get available roles: core + custom from permissions.config.ts
-export const AVAILABLE_ROLES: readonly string[] = [
-  ...CORE_TEAM_ROLES,
-  ...(CUSTOM_ROLES.additionalRoles ?? [])
-]
-
-// Role hierarchy (merged)
-export const ROLE_HIERARCHY: Record<string, number> = {
-  owner: 100,
-  admin: 50,
-  member: 10,
-  viewer: 1,
-  ...(CUSTOM_ROLES.hierarchy ?? {})
-}
+/** Team role hierarchy (restricted to AVAILABLE_ROLES) */
+export const ROLE_HIERARCHY: Record<string, number> = ${JSON.stringify(teamRoleConfig.hierarchy, null, 2)}
 
-// Role display names (merged)
-export const ROLE_DISPLAY_NAMES: Record<string, string> = {
-  owner: 'common.teamRoles.owner',
-  admin: 'common.teamRoles.admin',
-  member: 'common.teamRoles.member',
-  viewer: 'common.teamRoles.viewer',
-  ...(CUSTOM_ROLES.displayNames ?? {})
-}
+/** Team role display names (restricted to AVAILABLE_ROLES) */
+export const ROLE_DISPLAY_NAMES: Record<string, string> = ${JSON.stringify(teamRoleConfig.displayNames, null, 2)}
 
-// Role descriptions (merged)
-export const ROLE_DESCRIPTIONS: Record<string, string> = {
-  owner: 'Full team control, cannot be removed',
-  admin: 'Manage team members and settings',
-  member: 'Standard team access',
-  viewer: 'Read-only access to team resources',
-  ...(CUSTOM_ROLES.descriptions ?? {})
-}
+/** Team role descriptions (restricted to AVAILABLE_ROLES) */
+export const ROLE_DESCRIPTIONS: Record<string, string> = ${JSON.stringify(teamRoleConfig.descriptions, null, 2)}
 
 // Merge all permissions: core + teams + features + entities
 function buildAllPermissions(): ResolvedPermission[] {
@@ -438,7 +498,7 @@ export const PERMISSIONS_METADATA = {
   teamPermissions: TEAM_PERMISSIONS.length,
   featurePermissions: FEATURE_PERMISSIONS.length,
   entityPermissions: ENTITY_PERMISSIONS.length,
-  customRoles: CUSTOM_ROLES.additionalRoles?.length ?? 0,
+  customRoles: ${teamRoleConfig.customRolesCount},
   availableRoles: AVAILABLE_ROLES.length,
   categories: Object.keys(PERMISSIONS_BY_CATEGORY).length,
   generatedAt: '${new Date().toISOString()}',

package/styles/docs.css

@@ -80,3 +80,18 @@
 .docs-content hr {
   @apply my-8 border-border;
 }
+
+/* Mermaid diagrams: rendered client-side from a <pre class="mermaid"> marker */
+.docs-content pre.mermaid {
+  @apply my-6 p-0 bg-transparent border-0 text-center overflow-x-auto;
+  line-height: normal;
+}
+
+.docs-content pre.mermaid svg {
+  @apply max-w-full h-auto;
+}
+
+/* Raw source shown briefly before the client render replaces it */
+.docs-content pre.mermaid:not([data-processed="true"]) {
+  @apply text-sm text-muted-foreground;
+}

package/templates/app/(auth)/login/page.tsx

@@ -2,6 +2,8 @@ import type { Metadata } from 'next'
 import { LoginForm } from '@nextsparkjs/core/components/auth/forms/LoginForm'
 import { getTemplateOrDefault, getMetadataOrDefault } from '@nextsparkjs/core/lib/template-resolver'
 
+export const dynamic = 'force-dynamic'
+
 const defaultMetadata: Metadata = {
   title: 'Sign In',
   description: 'Sign in to your account to access the platform',

package/templates/app/(auth)/signup/page.tsx

@@ -6,6 +6,10 @@ import { getTemplateOrDefault, getMetadataOrDefault } from '@nextsparkjs/core/li
 import { AUTH_CONFIG } from '@nextsparkjs/core/lib/config'
 import { TeamService } from '@nextsparkjs/core/lib/services'
 
+// This page reads DB state (TeamService.hasGlobal) and redirect()s during render,
+// so it must render per-request and never be statically prerendered at build time.
+export const dynamic = 'force-dynamic'
+
 const defaultMetadata: Metadata = {
   title: 'Create Account',
   description: 'Create your account to start using our platform',