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

package/scripts/build/registry/__tests__/identifier.test.mjs

@@ -0,0 +1,65 @@
+/**
+ * Tests for identifier safety in generated registries.
+ *
+ * The aliases the registries import under are built from user-chosen names, and
+ * an invalid one is not a local problem: every route reaches the app through
+ * these files, so a single `as 7startupsAppConfig` stops the whole project from
+ * parsing. Replacing hyphens — what this used to do — leaves that case open.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/identifier.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { toSafeIdentifier } from '../generators/identifier.mjs'
+
+/** What the generated files are fed to: an ES module parser. */
+function isValidIdentifier(value) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value)
+}
+
+test('leaves a name that is already an identifier alone', () => {
+  assert.equal(toSafeIdentifier('default'), 'default')
+  assert.equal(toSafeIdentifier('myTheme'), 'myTheme')
+  assert.equal(toSafeIdentifier('theme_2'), 'theme_2')
+})
+
+test('replaces the characters a directory name allows and an identifier does not', () => {
+  assert.equal(toSafeIdentifier('my-theme'), 'my_theme')
+  assert.equal(toSafeIdentifier('my.theme'), 'my_theme')
+  assert.equal(toSafeIdentifier('my theme'), 'my_theme')
+  assert.equal(toSafeIdentifier('@scope/name'), '_scope_name')
+})
+
+test('prefixes a leading digit', () => {
+  assert.equal(toSafeIdentifier('7startups'), '_7startups')
+  assert.equal(toSafeIdentifier('123-app'), '_123_app')
+})
+
+test('never returns an empty identifier', () => {
+  assert.equal(toSafeIdentifier(''), '_')
+  assert.equal(toSafeIdentifier('---'), '___')
+})
+
+test('every result is a valid identifier, suffixed or not', () => {
+  const names = [
+    'default', 'my-theme', '7startups', '123-app', 'a.b.c', '', '---',
+    '2026', 'über-theme', 'theme!', '9', '_private', '$dollar',
+  ]
+
+  for (const name of names) {
+    const safe = toSafeIdentifier(name)
+    assert.ok(isValidIdentifier(safe), `${JSON.stringify(name)} produced ${JSON.stringify(safe)}`)
+    // The generators append a role to the alias, so that has to stay valid too
+    assert.ok(isValidIdentifier(`${safe}AppConfig`), `${safe}AppConfig is not an identifier`)
+  }
+})
+
+test('distinct names stay distinct where it matters', () => {
+  // Themes sit in one directory, so their names cannot collide after cleaning
+  // unless they differed only by a separator — which the filesystem allows.
+  // Documented rather than fixed: the alias is cosmetic, the registry is keyed
+  // by the real name.
+  assert.equal(toSafeIdentifier('my-theme'), toSafeIdentifier('my.theme'))
+})

package/scripts/build/registry/__tests__/page-generator.test.mjs

@@ -0,0 +1,430 @@
+/**
+ * Tests for the page-generator's route-level export handling.
+ *
+ * Next.js only reads route segment config (`revalidate`, `dynamic`, etc.)
+ * when it's a literal `export const` declared directly in the route file -
+ * a re-export is silently ignored and the default config is used instead
+ * (#191). The generator has to tell the two kinds of route export apart:
+ * segment config gets re-declared as a literal, everything else (metadata,
+ * generateMetadata, ...) can be forwarded with a plain re-export.
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/page-generator.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+
+import {
+  SEGMENT_CONFIG_EXPORTS,
+  MODULE_LEVEL_EXPORTS,
+  extractRouteExports,
+  generateTemplatePage,
+  generateMissingPages,
+} from '../post-build/page-generator.mjs'
+
+const FIXTURE_FILE = '/virtual/theme/templates/(public)/page.tsx'
+const FIXTURE_FILE_PATTERN = FIXTURE_FILE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+// --- helpers for the content-generation tests ------------------------------
+
+async function createProjectRoot() {
+  return mkdtemp(join(tmpdir(), 'nextspark-page-generator-test-'))
+}
+
+// generateTemplatePage resolves '@/...' template paths against the
+// generator's module-level rootDir, which is only ever set as a side effect
+// of generateMissingPages. Templates being empty makes it a no-op beyond
+// that assignment (cleanupOrphanedTemplates returns early when app/(templates)
+// doesn't exist yet under the given root).
+async function useProjectRoot(root) {
+  await generateMissingPages([], { projectRoot: root })
+}
+
+async function writeThemeTemplate(root, relativePath, content) {
+  const absolutePath = join(root, 'contents/themes/testtheme/templates', relativePath)
+  await mkdir(dirname(absolutePath), { recursive: true })
+  await writeFile(absolutePath, content, 'utf8')
+  return `@/contents/themes/testtheme/templates/${relativePath}`
+}
+
+// --- the two exported export-name tables ------------------------------------
+
+test('segment config and module-level export lists do not overlap', () => {
+  const overlap = SEGMENT_CONFIG_EXPORTS.filter(name => MODULE_LEVEL_EXPORTS.includes(name))
+  assert.deepEqual(overlap, [])
+})
+
+test('experimental_ppr is one of the tracked segment config keys', () => {
+  assert.ok(SEGMENT_CONFIG_EXPORTS.includes('experimental_ppr'))
+})
+
+// --- extractRouteExports: valid segment config literals ---------------------
+
+test('a number literal is captured as segment config', async () => {
+  const { segmentConfig } = await extractRouteExports('export const maxDuration = 30\n', FIXTURE_FILE)
+  assert.equal(segmentConfig.maxDuration, 30)
+})
+
+test('revalidate = false is captured as a literal, not treated as absent', async () => {
+  const { segmentConfig } = await extractRouteExports('export const revalidate = false\n', FIXTURE_FILE)
+  assert.equal(segmentConfig.revalidate, false)
+})
+
+test('a valid enum string is captured', async () => {
+  const { segmentConfig } = await extractRouteExports("export const dynamic = 'force-static'\n", FIXTURE_FILE)
+  assert.equal(segmentConfig.dynamic, 'force-static')
+})
+
+test('an array of strings is captured', async () => {
+  const { segmentConfig } = await extractRouteExports("export const preferredRegion = ['iad1', 'sfo1']\n", FIXTURE_FILE)
+  assert.deepEqual(segmentConfig.preferredRegion, ['iad1', 'sfo1'])
+})
+
+test('a satisfies-wrapped literal is unwrapped and captured', async () => {
+  const { segmentConfig } = await extractRouteExports(
+    "export const runtime = 'edge' satisfies 'edge' | 'nodejs'\n",
+    FIXTURE_FILE
+  )
+  assert.equal(segmentConfig.runtime, 'edge')
+})
+
+test('an as-const-wrapped literal is unwrapped and captured', async () => {
+  const { segmentConfig } = await extractRouteExports('export const dynamicParams = false as const\n', FIXTURE_FILE)
+  assert.equal(segmentConfig.dynamicParams, false)
+})
+
+test('a boolean literal is captured for experimental_ppr', async () => {
+  const { segmentConfig } = await extractRouteExports('export const experimental_ppr = true\n', FIXTURE_FILE)
+  assert.equal(segmentConfig.experimental_ppr, true)
+})
+
+// --- extractRouteExports: module-level exports -------------------------------
+
+test('an exported function declaration is a module-level export', async () => {
+  const { moduleExports, segmentConfig } = await extractRouteExports(
+    'export async function generateMetadata() { return {} }\n',
+    FIXTURE_FILE
+  )
+  assert.deepEqual(moduleExports, ['generateMetadata'])
+  assert.deepEqual(segmentConfig, {})
+})
+
+test('a locally re-exported function is a module-level export', async () => {
+  const source = `async function generateStaticParams() { return [] }\nexport { generateStaticParams }\n`
+  const { moduleExports } = await extractRouteExports(source, FIXTURE_FILE)
+  assert.deepEqual(moduleExports, ['generateStaticParams'])
+})
+
+test('an exported const object (metadata) is a module-level export, value untouched', async () => {
+  const source = `export const metadata = { title: 'Blog' }\n`
+  const { moduleExports, segmentConfig } = await extractRouteExports(source, FIXTURE_FILE)
+  assert.deepEqual(moduleExports, ['metadata'])
+  assert.deepEqual(segmentConfig, {})
+})
+
+// --- extractRouteExports: what does NOT count as an export -------------------
+
+test('a commented-out export is not detected', async () => {
+  const source = '// export const revalidate = 60\nexport default function Page() { return null }\n'
+  const { segmentConfig } = await extractRouteExports(source, FIXTURE_FILE)
+  assert.deepEqual(segmentConfig, {})
+})
+
+test('export syntax inside a string literal is not detected', async () => {
+  const source = 'const code = "export const revalidate = 60"\nexport default function Page() { return null }\n'
+  const { segmentConfig } = await extractRouteExports(source, FIXTURE_FILE)
+  assert.deepEqual(segmentConfig, {})
+})
+
+// --- extractRouteExports: invalid segment config must throw ------------------
+
+test('an expression value fails with an error naming the file and the key', async () => {
+  await assert.rejects(
+    () => extractRouteExports('export const revalidate = 60 * 60\n', FIXTURE_FILE),
+    error => {
+      assert.match(error.message, new RegExp(FIXTURE_FILE_PATTERN))
+      assert.match(error.message, /"revalidate"/)
+      assert.match(error.message, /literal/)
+      return true
+    }
+  )
+})
+
+test('an identifier value fails', async () => {
+  const source = 'const HOUR = 3600\nexport const revalidate = HOUR\n'
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /"revalidate"/)
+})
+
+test('re-exporting a segment config key from another module fails', async () => {
+  const source = "export { revalidate } from './shared-config'\n"
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /re-exported from another module/)
+})
+
+test('a local export specifier (no inline const) fails for a segment config key', async () => {
+  const source = 'const revalidate = 60\nexport { revalidate }\n'
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /"revalidate"/)
+})
+
+test('let/var for a segment config key fails', async () => {
+  const source = "export let dynamic = 'force-static'\n"
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /"let" or "var"/)
+})
+
+test('a value outside the schema fails', async () => {
+  const source = "export const dynamic = 'nonsense'\n"
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /outside what Next\.js accepts/)
+})
+
+test('a negative maxDuration fails schema validation', async () => {
+  const source = 'export const maxDuration = -5\n'
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /"maxDuration"/)
+})
+
+test('an array with a non-string element fails schema validation', async () => {
+  const source = "export const preferredRegion = ['iad1', 42]\n"
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), /"preferredRegion"/)
+})
+
+test('the error names the line the bad export is declared on', async () => {
+  const source = "import { x } from 'y'\n\nexport const revalidate = computeRevalidate()\n"
+  await assert.rejects(() => extractRouteExports(source, FIXTURE_FILE), new RegExp(`${FIXTURE_FILE_PATTERN}:3`))
+})
+
+// --- generated page content ---------------------------------------------------
+
+test('the generated page re-declares segment config as a literal and forwards module exports separately', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(
+      root,
+      '(public)/blog/[slug]/page.tsx',
+      "export async function generateMetadata() { return {} }\nexport const revalidate = 3600\nexport default function Page() { return null }\n"
+    )
+
+    const outputPath = join(root, 'app/(templates)/(public)/blog/[slug]/page.tsx')
+    await generateTemplatePage(
+      { appPath: 'app/(public)/blog/[slug]/page.tsx', templateType: 'page', name: '(public)/blog/[slug]/page', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /export const revalidate = 3600/)
+    assert.match(generated, /export \{ generateMetadata \} from '@\/contents\/themes\/testtheme\/templates\/\(public\)\/blog\/\[slug\]\/page'/)
+
+    const exportBlockLine = generated.split('\n').find(line => line.startsWith('export {'))
+    assert.ok(exportBlockLine, 'expected an export {} re-export line')
+    for (const key of SEGMENT_CONFIG_EXPORTS) {
+      assert.ok(!exportBlockLine.includes(key), `segment config key "${key}" must not appear in export {}`)
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a page with no route-level exports is generated unchanged (no forwarded-exports section)', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(root, 'plain/page.tsx', 'export default function Page() { return null }\n')
+
+    const outputPath = join(root, 'app/(templates)/plain/page.tsx')
+    await generateTemplatePage(
+      { appPath: 'app/plain/page.tsx', templateType: 'page', name: 'plain/page', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.doesNotMatch(generated, /export const/)
+    assert.doesNotMatch(generated, /export \{/)
+    assert.match(generated, /export default TemplateComponent\n$/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('an invalid segment config value fails page generation instead of being silently dropped', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(
+      root,
+      'broken/page.tsx',
+      'export const revalidate = process.env.REVALIDATE\nexport default function Page() { return null }\n'
+    )
+
+    const outputPath = join(root, 'app/(templates)/broken/page.tsx')
+    await assert.rejects(
+      () =>
+        generateTemplatePage(
+          { appPath: 'app/broken/page.tsx', templateType: 'page', name: 'broken/page', templatePath },
+          outputPath
+        ),
+      /"revalidate"/
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a layout with a default export and metadata forwards both, unlike the previous component-only behavior', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(
+      root,
+      'dashboard/layout.tsx',
+      "export const metadata = { title: 'Dashboard' }\nexport default function Layout({ children }) { return children }\n"
+    )
+
+    const outputPath = join(root, 'app/(templates)/dashboard/layout.tsx')
+    await generateTemplatePage(
+      { appPath: 'app/dashboard/layout.tsx', templateType: 'layout', name: 'dashboard/layout', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /import TemplateComponent from/)
+    assert.match(generated, /export \{ metadata \} from/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a layout template with no exports at all still gets the plain pass-through wrapper', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(root, 'empty/layout.tsx', '')
+
+    const outputPath = join(root, 'app/(templates)/empty/layout.tsx')
+    await generateTemplatePage(
+      { appPath: 'app/empty/layout.tsx', templateType: 'layout', name: 'empty/layout', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /Layout template - empty template file/)
+    assert.doesNotMatch(generated, /export \{/)
+    assert.doesNotMatch(generated, /export const/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+// --- default export detection (decides component import vs pass-through) ----
+
+for (const [label, source, expected] of [
+  ['export default function', 'export default function Layout({ children }) { return children }\n', true],
+  ['export default of a declared identifier', 'const Layout = ({ children }) => children\nexport default Layout\n', true],
+  ['a local export clause naming default', 'function Layout({ children }) { return children }\nexport { Layout as default }\n', true],
+  ['a default re-exported from another module', "export { default } from './shell'\n", true],
+  ['a comment that mentions export default', "// Intentionally no export default: metadata-only layout.\nexport const metadata = { title: 'Docs' }\n", false],
+  ['a string that contains export default', "export const metadata = { title: 'export default' }\n", false],
+  ['a type-only default', 'type Props = { title: string }\nexport type { Props as default }\n', false],
+]) {
+  test(`hasDefaultExport is ${expected} for ${label}`, async () => {
+    const { hasDefaultExport } = await extractRouteExports(source, FIXTURE_FILE)
+    assert.equal(hasDefaultExport, expected)
+  })
+}
+
+test('a metadata-only layout whose comment mentions export default gets the pass-through, not an import of a missing default', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(
+      root,
+      'docs/layout.tsx',
+      "// Intentionally no export default: metadata-only layout.\nexport const metadata = { title: 'Docs' }\n"
+    )
+
+    const outputPath = join(root, 'app/(templates)/docs/layout.tsx')
+    await generateTemplatePage(
+      { appPath: 'app/docs/layout.tsx', templateType: 'layout', name: 'docs/layout', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /Layout template - metadata-only/)
+    assert.doesNotMatch(generated, /import TemplateComponent from/)
+    assert.match(generated, /export \{ metadata \} from/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a layout exported through `export { X as default }` imports the theme component instead of a pass-through', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(
+      root,
+      'dashboard/layout.tsx',
+      'function DashboardLayout({ children }) { return children }\nexport { DashboardLayout as default }\n'
+    )
+
+    const outputPath = join(root, 'app/(templates)/dashboard/layout.tsx')
+    await generateTemplatePage(
+      { appPath: 'app/dashboard/layout.tsx', templateType: 'layout', name: 'dashboard/layout', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /import TemplateComponent from/)
+    assert.doesNotMatch(generated, /Pass-through component|empty template file/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+// --- parsing as the template's own kind of file ------------------------------
+
+test('a .ts template is parsed as TypeScript, so syntax a TSX parse reads as JSX keeps its default export', async () => {
+  const source = 'type Props = { children: string }\nconst Layout = <T>({ children }: T & Props): string => children\nexport default Layout\n'
+  const { hasDefaultExport } = await extractRouteExports(source, '/virtual/theme/templates/(public)/layout.ts')
+  assert.equal(hasDefaultExport, true)
+})
+
+test('a .ts layout with TypeScript-only syntax imports the theme component instead of a pass-through', async () => {
+  const root = await createProjectRoot()
+  try {
+    await useProjectRoot(root)
+    const templatePath = await writeThemeTemplate(
+      root,
+      'reports/layout.ts',
+      "import type { ReactNode } from 'react'\nconst ReportsLayout = <T>({ children }: T & { children: ReactNode }) => children\nexport default ReportsLayout\n"
+    )
+
+    const outputPath = join(root, 'app/(templates)/reports/layout.ts')
+    await generateTemplatePage(
+      { appPath: 'app/reports/layout.ts', templateType: 'layout', name: 'reports/layout', templatePath },
+      outputPath
+    )
+
+    const generated = await readFile(outputPath, 'utf8')
+    assert.match(generated, /import TemplateComponent from/)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a template that does not parse fails with its file and line instead of being read in part', async () => {
+  const source = 'export const revalidate = 60\nexport default function Page( {\n'
+  await assert.rejects(
+    () => extractRouteExports(source, FIXTURE_FILE),
+    new RegExp(`${FIXTURE_FILE_PATTERN}:\\d+: the template does not parse`)
+  )
+})
+
+test('syntax Next.js parses but the installed TypeScript does not (a source phase import) is read instead of rejected', async () => {
+  const source = "import source wasm from './module.wasm'\nexport const runtime = 'edge'\nexport default wasm\n"
+  for (const file of ['/virtual/theme/templates/(public)/page.ts', FIXTURE_FILE]) {
+    const { segmentConfig, hasDefaultExport } = await extractRouteExports(source, file)
+    assert.deepEqual(segmentConfig, { runtime: 'edge' }, file)
+    assert.equal(hasDefaultExport, true, file)
+  }
+})

package/scripts/build/registry/__tests__/scheduled-actions-registry.test.mjs

@@ -0,0 +1,41 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { generateScheduledActionsRegistry } from '../generators/scheduled-actions-registry.mjs'
+
+const theme = (name) => ({
+  name,
+  hasScheduledActions: true,
+  scheduledActionsPath: `@/contents/themes/${name}/lib/scheduled-actions`,
+})
+
+test('generates a registry for a theme with scheduled actions', () => {
+  const out = generateScheduledActionsRegistry([theme('default')], {})
+
+  assert.match(out, /import \* as defaultScheduledActions from '@\/contents\/themes\/default\/lib\/scheduled-actions'/)
+  assert.match(out, /'default': \{/)
+  assert.match(out, /registerAllHandlers: defaultScheduledActions\.registerAllHandlers/)
+})
+
+test('a theme name that is not a valid identifier still produces one', () => {
+  const out = generateScheduledActionsRegistry([theme('7startups'), theme('my-theme')], {})
+
+  assert.match(out, /import \* as _7startupsScheduledActions from/)
+  assert.match(out, /import \* as my_themeScheduledActions from/)
+  assert.doesNotMatch(out, /import \* as 7startups/)
+})
+
+// The generated file is TypeScript shipped to the project: a build-script import
+// leaking into it would not resolve there.
+test('does not leak the generator\'s own imports into the generated file', () => {
+  const out = generateScheduledActionsRegistry([theme('default')], {})
+
+  assert.doesNotMatch(out, /identifier\.mjs/)
+})
+
+test('a project with no scheduled actions still gets a valid registry', () => {
+  const out = generateScheduledActionsRegistry([{ name: 'starter', hasScheduledActions: false }], {})
+
+  assert.match(out, /SCHEDULED_ACTIONS_REGISTRY/)
+  assert.doesNotMatch(out, /starterScheduledActions/)
+})

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

@@ -0,0 +1,89 @@
+/**
+ * Tests for the template-registry generator.
+ *
+ * What matters here is the BINDING the generator emits. A static
+ * `import Template_0 from '...'` per template makes every route that touches
+ * the registry pull in the whole template graph (#183), so both registries
+ * have to emit a deferred import instead — and the server one has to do it
+ * without a Suspense boundary, which would let a response commit a 200 before
+ * a template's own notFound() runs (#129).
+ *
+ * Run: node --test packages/core/scripts/build/registry/__tests__/template-registry.test.mjs
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  generateTemplateRegistry,
+  generateTemplateRegistryClient
+} from '../generators/template-registry.mjs'
+
+const pageTemplate = {
+  name: '(public)/page',
+  themeName: 'default',
+  templateType: 'page',
+  fileName: 'page.tsx',
+  relativePath: '(public)/page.tsx',
+  appPath: 'app/(public)/page.tsx',
+  templatePath: '@/contents/themes/default/templates/(public)/page.tsx',
+  priority: 10
+}
+
+const protectedTemplate = {
+  ...pageTemplate,
+  name: 'dashboard/layout',
+  templateType: 'layout',
+  fileName: 'layout.meta.ts',
+  relativePath: 'dashboard/layout.meta.ts',
+  appPath: 'app/dashboard/layout.tsx',
+  templatePath: '@/contents/themes/default/templates/dashboard/layout.meta.ts'
+}
+
+const config = { outputDir: '/tmp/registries', projectRoot: '/tmp/project' }
+
+test('server registry defers the import instead of hoisting a static one', () => {
+  const out = generateTemplateRegistry([pageTemplate], config)
+
+  assert.match(
+    out,
+    /component: lazyTemplate\('app\/\(public\)\/page\.tsx', \(\) => import\('@\/contents\/themes\/default\/templates\/\(public\)\/page'\)\)/
+  )
+  assert.doesNotMatch(out, /^import Template_\d+ from/m)
+})
+
+test('names the template in the error when it has no default export', () => {
+  const out = generateTemplateRegistry([pageTemplate], config)
+
+  // Without the module loaded up front, React would otherwise fail with a bare
+  // "invalid element type" and no clue which template is at fault
+  assert.match(out, /has no default export/)
+  assert.match(out, /if \(!templateModule\.default\)/)
+})
+
+test('server registry loads templates without a Suspense boundary', () => {
+  const out = generateTemplateRegistry([pageTemplate], config)
+
+  // An async Server Component awaits inline; next/dynamic would wrap the
+  // template in Suspense and break notFound()'s hold on the status code.
+  assert.match(out, /return async function TemplateOverride/)
+  assert.doesNotMatch(out, /^import .* from 'next\/dynamic'/m)
+})
+
+test('metadata-only templates still carry no component', () => {
+  const out = generateTemplateRegistry([protectedTemplate], config)
+
+  assert.match(out, /component: null/)
+  assert.doesNotMatch(out, /layout\.meta'\)\)/)
+})
+
+test('client registry defers the import through next/dynamic', async () => {
+  const out = await generateTemplateRegistryClient([pageTemplate], config)
+
+  assert.match(out, /import dynamic from 'next\/dynamic'/)
+  assert.match(
+    out,
+    /'app\/\(public\)\/page\.tsx': dynamic\(\(\) => import\('@\/contents\/themes\/default\/templates\/\(public\)\/page'\)\)/
+  )
+  assert.doesNotMatch(out, /^import ClientTemplate_\d+ from/m)
+})