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

package/scripts/build/registry/__tests__/template-registry.test.mjs

@@ -13,13 +13,17 @@
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, mkdir, readdir, readFile, writeFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 import {
   generateTemplateRegistry,
-  generateTemplateRegistryClient
+  generateTemplateRegistryClient,
+  generateTemplateScopeRegistries
 } from '../generators/template-registry.mjs'
 import { analyzeTemplates } from '../post-build/page-generator.mjs'
 
@@ -45,6 +49,7 @@ const protectedTemplate = {
 }
 
 const config = { outputDir: '/tmp/registries', projectRoot: '/tmp/project' }
+const CORE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..')
 
 // The registry build parses the templates once, with analyzeTemplates, and
 // hands the same analysis to both registries. These do the same.
@@ -357,3 +362,332 @@ test('a layout with no default export is component: null on the server and has n
     await rm(root, { recursive: true, force: true })
   }
 })
+
+test('route scopes isolate template imports, retain empty fallbacks, and preserve the full registries', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    const publicPath = await writeThemeTemplate(
+      root,
+      '(public)/page.tsx',
+      'export default function PublicTemplate() { return null }\n'
+    )
+    const aiPath = await writeThemeTemplate(
+      root,
+      'ai/page.tsx',
+      'export default function AiTemplate() { return null }\n'
+    )
+    const metadataPath = await writeThemeTemplate(
+      root,
+      'layout.meta.ts',
+      "export const metadata = { title: 'Theme brand' }\n"
+    )
+    await writeAppRoute(root, 'app/(public)/page.tsx')
+    await writeAppRoute(root, 'app/ai/page.tsx')
+    await writeAppRoute(root, 'app/(auth)/empty/page.tsx')
+    await writeAppRoute(root, 'app/layout.tsx')
+
+    const templates = [
+      { ...pageTemplate, themeName: 'public', templatePath: publicPath },
+      { ...pageTemplate, name: 'ai/page', themeName: 'ai', relativePath: 'ai/page.tsx', appPath: 'app/ai/page.tsx', templatePath: aiPath },
+      {
+        ...protectedTemplate,
+        name: 'root/layout',
+        themeName: 'brand',
+        relativePath: 'layout.meta.ts',
+        appPath: 'app/layout.tsx',
+        templatePath: metadataPath,
+        metadata: { title: 'Theme brand' }
+      }
+    ]
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const analysis = await analyzeTemplates(templates, scopedConfig)
+    const { files } = await generateTemplateScopeRegistries(templates, scopedConfig, analysis)
+    const file = suffix => files.find(candidate => candidate.path.endsWith(suffix))?.content
+    const publicServer = file('/template-scopes/server/(public)/page.ts')
+    const aiServer = file('/template-scopes/server/ai/page.ts')
+    const publicClient = file('/template-scopes/client/(public)/page.ts')
+    const emptyServer = file('/template-scopes/server/(auth)/empty/page.ts')
+    const protectedServer = file('/template-scopes/server/layout.ts')
+
+    assert.match(publicServer, /templates\/\(public\)\/page'\)\)/)
+    assert.doesNotMatch(publicServer, /templates\/ai\/page/)
+    assert.match(aiServer, /templates\/ai\/page'\)\)/)
+    assert.doesNotMatch(aiServer, /templates\/\(public\)\/page/)
+    assert.match(publicClient, /dynamic\(\(\) => import\('@\/contents\/themes\/testtheme\/templates\/\(public\)\/page'\)\)/)
+    assert.doesNotMatch(publicClient, /templates\/ai\/page/)
+    assert.match(emptyServer, /TEMPLATE_REGISTRY: Record<string, TemplateRegistryEntry> = \{\s*\}/)
+    assert.match(emptyServer, /export function getTemplateOrDefault/)
+    assert.doesNotMatch(emptyServer, /TemplateService|template-registry'/)
+    assert.match(protectedServer, /component: null/)
+    assert.match(protectedServer, /canOverrideMetadata/)
+
+    const full = await generateTemplateRegistry(templates, scopedConfig, analysis)
+    assert.match(full, /app\/\(public\)\/page\.tsx/)
+    assert.match(full, /app\/ai\/page\.tsx/)
+    const client = await generateTemplateRegistryClient(templates, scopedConfig, analysis)
+    assert.doesNotMatch(client, /layout\.tsx/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+// The scoped module is TypeScript, but its resolvers have no runtime
+// dependencies beyond the generated registry and protected-path predicates.
+// Execute exactly that emitted code so semantic parity is not just a snapshot.
+function scopedResolvers(scopeContent, registry, canOverrideComponent = () => true, canOverrideMetadata = () => true) {
+  const start = scopeContent.indexOf('export function hasTemplateOverride')
+  assert.notEqual(start, -1, 'scope should contain scoped resolvers')
+  const emitted = scopeContent
+    .slice(start)
+    .replace('export function hasTemplateOverride(appPath: string): boolean {', 'function hasTemplateOverride(appPath) {')
+    .replace('export function getTemplateComponent(appPath: string): any | null {', 'function getTemplateComponent(appPath) {')
+    .replace('export function getTemplateOrDefault<T = any>(appPath: string, defaultComponent: T): T {', 'function getTemplateOrDefault(appPath, defaultComponent) {')
+    .replace('component as T', 'component')
+    .replace('export function getMetadataOrDefault(appPath: string, defaultMetadata: any): any {', 'function getMetadataOrDefault(appPath, defaultMetadata) {')
+  return Function('TEMPLATE_REGISTRY', 'canOverrideComponent', 'canOverrideMetadata', `${emitted}\nreturn { hasTemplateOverride, getTemplateComponent, getTemplateOrDefault, getMetadataOrDefault }`)(
+    registry,
+    canOverrideComponent,
+    canOverrideMetadata
+  )
+}
+
+test('scoped metadata runtime preserves legacy truthy fallback semantics', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    await writeAppRoute(root, 'app/metadata.ts')
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const { files } = await generateTemplateScopeRegistries([], scopedConfig)
+    const scope = files.find(file => file.path.endsWith('/template-scopes/server/metadata.ts')).content
+    const fallback = { title: 'application default' }
+
+    for (const metadata of [false, 0, '', null, undefined]) {
+      const { getMetadataOrDefault } = scopedResolvers(scope, { 'app/metadata.ts': { template: { metadata } } })
+      assert.equal(getMetadataOrDefault('app/metadata.ts', fallback), fallback)
+    }
+    const override = { title: 'theme override' }
+    const { getMetadataOrDefault } = scopedResolvers(scope, { 'app/metadata.ts': { template: { metadata: override } } })
+    assert.equal(getMetadataOrDefault('app/metadata.ts', fallback), override)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('scoped dynamic lookups preserve TemplateService has/get fallback semantics', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    await writeAppRoute(root, 'app/(public)/[...slug]/page.tsx')
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const { files } = await generateTemplateScopeRegistries([], scopedConfig)
+    const scope = files.find(file => file.path.endsWith('/template-scopes/server/(public)/[...slug]/page.ts')).content
+    const component = () => 'template'
+    const { hasTemplateOverride, getTemplateComponent } = scopedResolvers(scope, {
+      'app/(public)/blog/[slug]/page.tsx': { component },
+      'app/(public)/metadata-only/page.tsx': { component: null }
+    })
+
+    assert.equal(hasTemplateOverride('app/(public)/blog/[slug]/page.tsx'), true)
+    assert.equal(hasTemplateOverride('app/(public)/missing/page.tsx'), false)
+    assert.equal(getTemplateComponent('app/(public)/blog/[slug]/page.tsx'), component)
+    assert.equal(getTemplateComponent('app/(public)/metadata-only/page.tsx'), null)
+    assert.equal(getTemplateComponent('app/(public)/missing/page.tsx'), null)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('scopes use separate server/client trees and reject extension output ambiguity before writes', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    await writeAppRoute(root, 'app/foo.ts')
+    await writeAppRoute(root, 'app/foo.client.ts')
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const { files } = await generateTemplateScopeRegistries([], scopedConfig)
+    const paths = new Set(files.map(file => file.path))
+    for (const path of [
+      '/template-scopes/server/foo.ts',
+      '/template-scopes/client/foo.ts',
+      '/template-scopes/server/foo.client.ts',
+      '/template-scopes/client/foo.client.ts'
+    ]) assert.ok([...paths].some(candidate => candidate.endsWith(path)), `missing ${path}`)
+
+    await writeAppRoute(root, 'app/ambiguous.ts')
+    await writeAppRoute(root, 'app/ambiguous.tsx')
+    await assert.rejects(
+      () => generateTemplateScopeRegistries([], scopedConfig),
+      /Ambiguous template scope output .*ambiguous\.ts.*app\/ambiguous\.ts.*app\/ambiguous\.tsx/s
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('client scopes exclude side-effect and multiline server-only imports with either quote style', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-registry-test-'))
+  try {
+    const sideEffectPath = await writeThemeTemplate(root, 'server-only/page.tsx', "import 'server-only'\nexport default function Page() { return null }\n")
+    const multilinePath = await writeThemeTemplate(root, 'quoted/layout.tsx', 'import {\n  marker\n} from "server-only"\nexport default function Layout() { return null }\n')
+    const templates = [
+      { ...pageTemplate, appPath: 'app/server-only/page.tsx', relativePath: 'server-only/page.tsx', templatePath: sideEffectPath },
+      { ...pageTemplate, appPath: 'app/quoted/layout.tsx', templateType: 'layout', relativePath: 'quoted/layout.tsx', templatePath: multilinePath }
+    ]
+    const out = await generateClientRegistry(templates, { outputDir: join(root, '.nextspark/registries'), projectRoot: root })
+    assert.doesNotMatch(out, /app\/server-only\/page\.tsx/)
+    assert.doesNotMatch(out, /app\/quoted\/layout\.tsx/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('scoped resolver keeps highest template selection while empty and protected scopes fall back', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    const lowPath = await writeThemeTemplate(root, 'priority/low.tsx', 'export default function Low() { return null }\n')
+    const highPath = await writeThemeTemplate(root, 'priority/high.tsx', 'export default function High() { return null }\n')
+    await writeAppRoute(root, 'app/priority/page.tsx')
+    await writeAppRoute(root, 'app/empty/page.tsx')
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const templates = [
+      { ...pageTemplate, appPath: 'app/priority/page.tsx', templatePath: lowPath, priority: 1 },
+      { ...pageTemplate, appPath: 'app/priority/page.tsx', templatePath: highPath, priority: 10 }
+    ]
+    const { files } = await generateTemplateScopeRegistries(templates, scopedConfig, await analyzeTemplates(templates, scopedConfig))
+    const priorityScope = files.find(file => file.path.endsWith('/template-scopes/server/priority/page.ts')).content
+    const emptyScope = files.find(file => file.path.endsWith('/template-scopes/server/empty/page.ts')).content
+    assert.ok(priorityScope.indexOf(highPath) < priorityScope.indexOf(lowPath), 'highest-priority template is the selected entry')
+
+    const fallback = () => 'fallback'
+    const override = () => 'override'
+    assert.equal(scopedResolvers(emptyScope, {}).getTemplateOrDefault('app/empty/page.tsx', fallback), fallback)
+    assert.equal(scopedResolvers(priorityScope, { 'app/priority/page.tsx': { component: override } }).getTemplateOrDefault('app/priority/page.tsx', fallback), override)
+    assert.equal(scopedResolvers(priorityScope, { 'app/priority/page.tsx': { component: override } }, () => false).getTemplateOrDefault('app/priority/page.tsx', fallback), fallback)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('dynamic route scopes contain only their runtime target family, not the full registry', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    await writeAppRoute(root, 'app/(public)/[...slug]/page.tsx')
+    await writeAppRoute(root, 'app/dashboard/(main)/[entity]/[id]/page.tsx')
+
+    const publicDynamic = await writeThemeTemplate(root, '(public)/blog/[slug]/page.tsx', 'export default function Blog() { return null }\n')
+    const dashboardDetail = await writeThemeTemplate(root, 'dashboard/(main)/projects/[id]/page.tsx', 'export default function Project() { return null }\n')
+    const nestedDashboardDetail = await writeThemeTemplate(root, 'dashboard/(main)/boards/[id]/[cardId]/page.tsx', 'export default function Card() { return null }\n')
+    const dashboardAi = await writeThemeTemplate(root, 'dashboard/(main)/agent-multi/page.tsx', 'export default function Agent() { return null }\n')
+    const observability = await writeThemeTemplate(root, 'superadmin/ai-observability/page.tsx', 'export default function Observability() { return null }\n')
+    const templates = [
+      { ...pageTemplate, appPath: 'app/(public)/blog/[slug]/page.tsx', relativePath: '(public)/blog/[slug]/page.tsx', templatePath: publicDynamic },
+      { ...pageTemplate, appPath: 'app/dashboard/(main)/projects/[id]/page.tsx', relativePath: 'dashboard/(main)/projects/[id]/page.tsx', templatePath: dashboardDetail },
+      { ...pageTemplate, appPath: 'app/dashboard/(main)/boards/[id]/[cardId]/page.tsx', relativePath: 'dashboard/(main)/boards/[id]/[cardId]/page.tsx', templatePath: nestedDashboardDetail },
+      { ...pageTemplate, appPath: 'app/dashboard/(main)/agent-multi/page.tsx', relativePath: 'dashboard/(main)/agent-multi/page.tsx', templatePath: dashboardAi },
+      { ...pageTemplate, appPath: 'app/superadmin/ai-observability/page.tsx', relativePath: 'superadmin/ai-observability/page.tsx', templatePath: observability }
+    ]
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const { files } = await generateTemplateScopeRegistries(templates, scopedConfig, await analyzeTemplates(templates, scopedConfig))
+    const file = suffix => files.find(candidate => candidate.path.endsWith(suffix))?.content
+    const publicServer = file('/template-scopes/server/(public)/[...slug]/page.ts')
+    const publicClient = file('/template-scopes/client/(public)/[...slug]/page.ts')
+    const dashboardServer = file('/template-scopes/server/dashboard/(main)/[entity]/[id]/page.ts')
+
+    assert.match(publicServer, /templates\/\(public\)\/blog\/\[slug\]\/page'\)\)/)
+    assert.match(publicServer, /export function hasTemplateOverride/)
+    assert.match(publicServer, /export function getTemplateComponent/)
+    assert.doesNotMatch(publicServer, /agent-multi|ai-observability|projects\/\[id\]/)
+    assert.match(publicClient, /templates\/\(public\)\/blog\/\[slug\]\/page'\)\)/)
+    assert.doesNotMatch(publicClient, /agent-multi|ai-observability|projects\/\[id\]/)
+
+    assert.match(dashboardServer, /templates\/dashboard\/\(main\)\/projects\/\[id\]\/page'\)\)/)
+    assert.doesNotMatch(dashboardServer, /\(public\)\/blog|boards\/\[id\]\/\[cardId\]|agent-multi|ai-observability/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+async function scopedFiles(root) {
+  const directory = join(root, '.nextspark/registries/template-scopes')
+  const files = []
+  async function visit(path, relative = '') {
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      const entryPath = join(path, entry.name)
+      const entryRelative = relative ? `${relative}/${entry.name}` : entry.name
+      if (entry.isDirectory()) await visit(entryPath, entryRelative)
+      else if (entry.isFile()) files.push([entryRelative, await readFile(entryPath, 'utf8')])
+    }
+  }
+  await visit(directory)
+  return files.sort(([left], [right]) => left.localeCompare(right))
+}
+
+function runRegistryBuild(root) {
+  const result = spawnSync('node', ['scripts/build/registry.mjs'], {
+    cwd: CORE_DIR,
+    env: { ...process.env, NEXTSPARK_PROJECT_ROOT: root },
+    encoding: 'utf8',
+  })
+  assert.equal(result.status, 0, `${result.stdout}${result.stderr}`)
+}
+
+function withoutBuildTimestamps(content) {
+  return content.replace(/(Generated at|generatedAt): .*$/gm, '$1: <build-time>')
+}
+
+test('complete builds exclude generated template pages and layout copies from route scopes, then prune both in one build', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-build-test-'))
+  try {
+    await writeFile(join(root, '.env'), 'NEXT_PUBLIC_ACTIVE_THEME=acme\n')
+    await writeFile(join(root, 'package.json'), '{}\n')
+    await writeAppRoute(root, 'app/shop/layout.tsx', 'export default function ShopLayout({ children }) { return children }\n')
+    await writeAppRoute(root, 'contents/themes/acme/config/theme.config.ts', 'export const acmeThemeConfig = {}\n')
+    const template = join(root, 'contents/themes/acme/templates/shop/page.tsx')
+    await mkdir(dirname(template), { recursive: true })
+    await writeFile(template, 'export default function ShopPage() { return null }\n')
+
+    runRegistryBuild(root)
+    const firstScopes = await scopedFiles(root)
+    assert.equal(existsSync(join(root, 'app/(templates)/shop/page.tsx')), true, 'the generated template page exists')
+    const generatedLayout = await readFile(join(root, 'app/(templates)/shop/layout.tsx'), 'utf8')
+    assert.match(generatedLayout, /copy of app\/shop\/layout\.tsx/)
+
+    runRegistryBuild(root)
+    const secondScopes = await scopedFiles(root)
+    assert.deepEqual(
+      secondScopes.map(([path]) => path),
+      firstScopes.map(([path]) => path),
+      'a generated page and copied layout do not become scopes on the next build'
+    )
+    assert.deepEqual(
+      secondScopes.map(([path, content]) => [path, withoutBuildTimestamps(content)]),
+      firstScopes.map(([path, content]) => [path, withoutBuildTimestamps(content)])
+    )
+
+    await rm(template)
+    runRegistryBuild(root)
+    const prunedScopes = await scopedFiles(root)
+    assert.equal(existsSync(join(root, 'app/(templates)/shop/page.tsx')), false, 'the removed template page is pruned in the same build')
+    assert.equal(existsSync(join(root, 'app/(templates)/shop/layout.tsx')), false, 'the generated layout copy is pruned in the same build')
+    assert.deepEqual(
+      prunedScopes.map(([path]) => path),
+      ['client/shop/layout.ts', 'server/shop/layout.ts'],
+      'only the real application layout keeps a scope after the template is removed'
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('server route scopes are marked server-only while client scopes remain client-safe', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'nextspark-template-scopes-test-'))
+  try {
+    await writeAppRoute(root, 'app/shop/page.tsx')
+    const scopedConfig = { outputDir: join(root, '.nextspark/registries'), projectRoot: root }
+    const { files } = await generateTemplateScopeRegistries([], scopedConfig)
+    const serverScope = files.find(file => file.path.endsWith('/template-scopes/server/shop/page.ts')).content
+    const clientScope = files.find(file => file.path.endsWith('/template-scopes/client/shop/page.ts')).content
+
+    assert.match(serverScope, /import 'server-only'/)
+    assert.doesNotMatch(clientScope, /server-only/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})

package/scripts/build/registry/__tests__/write-places.test.mjs

@@ -136,6 +136,32 @@ test('a directory the build lists that cannot be read is found', { skip: RUNS_AS
   }
 })
 
+test('only the generated template-scopes registry subtree may be a directory, and it is still guarded', async () => {
+  const { root, cleanup } = await directory()
+  const outside = await directory()
+  try {
+    await mkdir(join(root, 'app'), { recursive: true })
+    await writeIn(root, '.nextspark/registries/template-scopes/server/(public)/page.ts', '/** Auto-generated route-scoped template registry; do not edit. */\n')
+
+    assert.deepEqual(unsafeWritePlaces(root), [])
+
+    await symlink(join(outside.root, 'scope'), join(root, '.nextspark/registries/template-scopes/server/(public)/link'))
+    assert.deepEqual(unsafeWritePlaces(root), [
+      { path: '.nextspark/registries/template-scopes/server/(public)/link', problem: 'is a symlink' }
+    ])
+    await rm(join(root, '.nextspark/registries/template-scopes/server/(public)/link'))
+
+    await rm(join(root, '.nextspark/registries/template-scopes'), { recursive: true })
+    await writeIn(root, '.nextspark/registries/template-scopes', '')
+    assert.deepEqual(unsafeWritePlaces(root), [
+      { path: '.nextspark/registries/template-scopes', problem: 'is not a directory' }
+    ])
+  } finally {
+    await outside.cleanup()
+    await cleanup()
+  }
+})
+
 test('a .nextspark/backups/.gitignore counts as in place only as a readable file with * as its one pattern, and anything else is found', async () => {
   const contents = [
     ['*\n', 'in place'],

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

@@ -6,16 +6,15 @@
  * @module core/scripts/build/registry/generators/template-registry
  */
 
-import { readFile } from 'fs/promises'
-import { join, dirname } from 'path'
+import { lstat, readdir, readFile } from 'fs/promises'
+import { join, dirname, relative, sep } from 'path'
 import { fileURLToPath } from 'url'
 
 import { verbose } from '../../../utils/index.mjs'
-import {
-  canOverrideComponent
-} from '../../../../dist/config/protected-paths.js'
+import { canOverrideComponent } from '../../../../dist/config/protected-paths.js'
 import { convertCorePath } from '../config.mjs'
 import { analyzeTemplates, routeFileAction, templateAnalysisFor } from '../post-build/page-generator.mjs'
+import { loadTypeScriptFor } from '../shared/typescript-compiler.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -204,9 +203,32 @@ export const TEMPLATE_METADATA = {
  * @param {string} filePath - Path to the template file
  * @returns {Promise<boolean>} Whether the file has server-only exports
  */
-async function hasServerOnlyExports(filePath) {
+async function hasServerOnlyExports(filePath, projectRoot) {
   try {
     const content = await readFile(filePath, 'utf8')
+    // Prefer the compiler's import declarations: unlike a source scan they
+    // distinguish a real import from a comment/string and cover multiline
+    // named imports as well as the usual side-effect `import 'server-only'`.
+    try {
+      const ts = await loadTypeScriptFor(projectRoot)
+      const sourceFile = ts.createSourceFile(
+        filePath,
+        content,
+        ts.ScriptTarget.Latest,
+        true,
+        ts.getScriptKindFromFileName(filePath)
+      )
+      for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+          if (statement.moduleSpecifier.text === 'next/headers' || statement.moduleSpecifier.text === 'server-only') {
+            return true
+          }
+        }
+      }
+    } catch {
+      // A project without the compiler API can still use the deliberately
+      // anchored fallback below. The other checks have always been scans.
+    }
     // Check for server-only function exports
     const serverFunctionExports = [
       /export\s+(async\s+)?function\s+generateMetadata/,
@@ -223,8 +245,8 @@ async function hasServerOnlyExports(filePath) {
 
     // Check for server-only module imports
     const serverOnlyImports = [
-      /import\s+.*from\s+['"]next\/headers['"]/,
-      /import\s+.*from\s+['"]server-only['"]/,
+      /(?:^|[;\r\n])\s*import\s+(?:type\s+)?(?:(?:[\w*$][^;'"`]*?)\s+from\s+)?(['"])next\/headers\1\s*;?/m,
+      /(?:^|[;\r\n])\s*import\s+(?:type\s+)?(?:(?:[\w*$][^;'"`]*?)\s+from\s+)?(['"])server-only\1\s*;?/m,
     ]
 
     // Check if default export is an async function (server component marker in Next.js)
@@ -277,7 +299,7 @@ export async function generateTemplateRegistryClient(templates, config, analysis
       }
 
       // Check for server-only exports
-      const hasServerExports = await hasServerOnlyExports(actualFilePath)
+      const hasServerExports = await hasServerOnlyExports(actualFilePath, projectRoot)
       if (hasServerExports) {
         verbose(`Excluding ${appPath} from client registry (has server-only exports)`)
         return null
@@ -365,3 +387,174 @@ export function withTemplateOverrideForClient<P extends object>(appPath: string)
 }
 `
 }
+
+// Route scopes deliberately contain their own, small registry. In particular,
+// do not import TemplateService or the full template registry here: a route
+// importing a scope must not reconnect its bundle to every theme template.
+const SCOPE_MARKER = 'Auto-generated route-scoped template registry'
+const TYPE_SCRIPT_ROUTE = /\.(?:tsx|ts)$/
+
+/** Turn an app route filename into its matching safe server/client scope filename. */
+function scopeFileFor(appPath, scopeDirectory, client = false) {
+  if (typeof appPath !== 'string' || !appPath.startsWith('app/') || !TYPE_SCRIPT_ROUTE.test(appPath)) {
+    throw new Error(`Invalid template scope app path: ${String(appPath)}`)
+  }
+  const route = appPath.slice('app/'.length).replace(TYPE_SCRIPT_ROUTE, '')
+  const segments = route.split('/')
+  if (!route || segments.some(segment => !segment || segment === '.' || segment === '..' || segment.includes('\\'))) {
+    throw new Error(`Invalid template scope app path: ${appPath}`)
+  }
+  return join(scopeDirectory, client ? 'client' : 'server', `${route}.ts`)
+}
+
+/** Read actual route modules without following symlinks or descending into node_modules. */
+async function discoverAppRoutePaths(projectRoot) {
+  const appDirectory = join(projectRoot, 'app')
+  const routePaths = []
+  async function visit(directory) {
+    let entries
+    try {
+      entries = await readdir(directory, { withFileTypes: true })
+    } catch (error) {
+      if (error?.code === 'ENOENT') return
+      throw error
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules') continue
+      // The registry build writes generated template routes and layout copies
+      // here after scopes are planned. They are implementation artifacts, not
+      // application routes, so never let a later build turn them into scopes.
+      if (directory === appDirectory && entry.name === '(templates)') continue
+      const absolute = join(directory, entry.name)
+      // Dirent is a hint only; lstat prevents traversing a changed symlink.
+      const stat = await lstat(absolute)
+      if (stat.isSymbolicLink()) continue
+      if (stat.isDirectory()) await visit(absolute)
+      else if (stat.isFile() && TYPE_SCRIPT_ROUTE.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+        routePaths.push(`app/${relative(appDirectory, absolute).split(sep).join('/')}`)
+      }
+    }
+  }
+  await visit(appDirectory)
+  return routePaths
+}
+
+function scopedServerResolver(outputFilePath, config) {
+  const protectedPaths = convertCorePath('@/core/config/protected-paths', outputFilePath, config)
+  return `
+
+import { canOverrideComponent, canOverrideMetadata } from '${protectedPaths}'
+
+/**
+ * The two dynamic application routes need to ask about a runtime-generated
+ * app path. Keep this small compatibility surface local to their bounded
+ * scope instead of importing the global service, whose registry has every
+ * template in the application.
+ */
+export function hasTemplateOverride(appPath: string): boolean {
+  return appPath in TEMPLATE_REGISTRY
+}
+
+/** Return the selected component using the global service's get-component semantics. */
+export function getTemplateComponent(appPath: string): any | null {
+  return TEMPLATE_REGISTRY[appPath]?.component || null
+}
+
+/** Resolve only this route's selected template; no global registry is imported. */
+export function getTemplateOrDefault<T = any>(appPath: string, defaultComponent: T): T {
+  if (!canOverrideComponent(appPath)) return defaultComponent
+  const component = TEMPLATE_REGISTRY[appPath]?.component
+  return component ? component as T : defaultComponent
+}
+
+/** Resolve metadata from only this route's selected template. */
+export function getMetadataOrDefault(appPath: string, defaultMetadata: any): any {
+  if (!canOverrideMetadata(appPath)) return defaultMetadata
+  const metadata = TEMPLATE_REGISTRY[appPath]?.template?.metadata
+  return metadata ? metadata : defaultMetadata
+}
+`
+}
+
+const PUBLIC_DYNAMIC_CATCH_ALL_PATH = 'app/(public)/[...slug]/page.tsx'
+const DASHBOARD_DYNAMIC_DETAIL_PATH = 'app/dashboard/(main)/[entity]/[id]/page.tsx'
+
+/**
+ * The dynamic routes construct their target template path from an entity at
+ * runtime. Their scope therefore needs the possible templates for *that
+ * route family*, rather than an exact path that cannot be known at build time.
+ *
+ * These predicates intentionally describe the strings built in the two route
+ * modules. Do not widen them to an area prefix: doing so would recreate the
+ * full-registry fan-out this generator exists to avoid.
+ */
+function isPublicDynamicEntityTemplate(appPath) {
+  return /^app\/\(public\)\/(?:.+\/)?\[(?:slug|entity)\]\/page\.(?:tsx|ts)$/.test(appPath)
+}
+
+function isDashboardDynamicDetailTemplate(appPath) {
+  return /^app\/dashboard\/\(main\)\/[^/]+\/\[id\]\/page\.(?:tsx|ts)$/.test(appPath)
+}
+
+function templatesForScope(templates, scopeAppPath) {
+  return templates.filter(template => {
+    if (template.appPath === scopeAppPath) return true
+    if (scopeAppPath === PUBLIC_DYNAMIC_CATCH_ALL_PATH) {
+      return isPublicDynamicEntityTemplate(template.appPath)
+    }
+    if (scopeAppPath === DASHBOARD_DYNAMIC_DETAIL_PATH) {
+      return isDashboardDynamicDetailTemplate(template.appPath)
+    }
+    return false
+  })
+}
+
+/**
+ * Fail while constructing the complete write plan if two app route extensions
+ * normalize to the same scope module. This happens before registry.mjs can
+ * delete stale files or write any replacement scopes.
+ */
+function assertUniqueScopeOutputs(appPaths, scopeDirectory) {
+  const outputs = new Map()
+  for (const appPath of appPaths) {
+    for (const client of [false, true]) {
+      const outputPath = scopeFileFor(appPath, scopeDirectory, client)
+      const previous = outputs.get(outputPath)
+      if (previous && previous !== appPath) {
+        throw new Error(
+          `Ambiguous template scope output ${outputPath}: both ${previous} and ${appPath} normalize to this file. ` +
+          'Keep only one route extension (.ts or .tsx) for the route before generating registries.'
+        )
+      }
+      outputs.set(outputPath, appPath)
+    }
+  }
+}
+
+/**
+ * Generate route-scoped server/client modules as paths and content. The build
+ * writes this plan via safe-fs; empty scopes preserve a route fallback when a
+ * theme change removes its override.
+ */
+export async function generateTemplateScopeRegistries(templates, config, analysis = null) {
+  const scopeDirectory = join(config.outputDir, 'template-scopes')
+  const paths = new Set(await discoverAppRoutePaths(config.projectRoot))
+  for (const template of templates) paths.add(template.appPath)
+  assertUniqueScopeOutputs(paths, scopeDirectory)
+  const files = []
+  for (const appPath of [...paths].sort()) {
+    const selected = templatesForScope(templates, appPath)
+    const serverPath = scopeFileFor(appPath, scopeDirectory)
+    const clientPath = scopeFileFor(appPath, scopeDirectory, true)
+    const serverRegistry = await generateTemplateRegistry(selected, config, analysis)
+    const clientRegistry = await generateTemplateRegistryClient(selected, config, analysis)
+    files.push(
+      { path: serverPath, content: `/** ${SCOPE_MARKER}; do not edit. */\nimport 'server-only'\n${serverRegistry}${scopedServerResolver(serverPath, config)}` },
+      { path: clientPath, content: `/** ${SCOPE_MARKER}; do not edit. */\n${clientRegistry}` }
+    )
+  }
+  return { directory: scopeDirectory, files }
+}
+
+/** Marker used to restrict stale cleanup to files this generator owns. */
+export { SCOPE_MARKER }