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

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)
+})

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

@@ -0,0 +1,275 @@
+/**
+ * Icon Discovery
+ *
+ * Collects every lucide-react icon name the app can ask for by string at
+ * runtime, so the generated icon registry can import exactly those and let
+ * the bundler drop the rest of the icon set.
+ *
+ * Sources are exactly what resolveIcon can be handed, and all of them are
+ * source files (never the database):
+ * - entity configs (`icon: Users` — an identifier imported from lucide-react)
+ * - a theme's app.config (`customSidebarSections[].icon` — a string)
+ * - block configs (`icon: 'Grid'` — the block's own icon in the editor)
+ *
+ * What a block RENDERS is not here: page content names those icons in the page
+ * builder, so they live in the database. Those blocks keep resolving through
+ * the lucide namespace — deliberately, see themes' features-grid component.
+ *
+ * @module core/scripts/build/registry/discovery/icons
+ */
+
+import { readdir, readFile } from 'fs/promises'
+import { existsSync } from 'fs'
+import { createRequire } from 'module'
+import { join, dirname } from 'path'
+
+import { verbose, log } from '../../../utils/index.mjs'
+
+/**
+ * Icons the resolver falls back to when a name doesn't resolve. They are
+ * referenced from core components, not from any config, so nothing would
+ * discover them.
+ */
+const FALLBACK_ICONS = ['Box', 'Circle', 'Folder', 'LayoutGrid']
+
+/**
+ * Names lucide-react actually exports, read from its own barrel.
+ * A name that isn't there would become a broken named import in the
+ * generated registry, so unknown names are dropped with a warning instead.
+ * @param {object} config
+ * @returns {Set<string>|null} null when lucide-react can't be resolved
+ */
+async function readLucideExportNames(config) {
+  try {
+    const requireFromProject = createRequire(join(config.projectRoot, 'package.json'))
+    const pkgPath = requireFromProject.resolve('lucide-react/package.json')
+    const barrelPath = join(dirname(pkgPath), 'dist/esm/lucide-react.js')
+
+    if (!existsSync(barrelPath)) {
+      return null
+    }
+
+    const barrel = await readFile(barrelPath, 'utf8')
+    const names = new Set()
+    for (const match of barrel.matchAll(/default as ([A-Za-z_$][\w$]*)/g)) {
+      names.add(match[1])
+    }
+    return names.size > 0 ? names : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Which config files hold icons resolveIcon can be handed. Exported for tests.
+ *
+ * Separators are normalised first: the generator also runs on Windows, where
+ * join() produces '\\' and a '/'-shaped match would silently find nothing —
+ * leaving a registry with only its fallbacks, and every entity icon rendering
+ * as a Box.
+ */
+export function isIconSourcePath(filePath) {
+  const normalised = filePath.replace(/\\/g, '/')
+  return (
+    (normalised.includes('/entities/') && normalised.endsWith('.config.ts')) ||
+    (normalised.includes('/blocks/') && normalised.endsWith('/config.ts')) ||
+    normalised.endsWith('/config/app.config.ts')
+  )
+}
+
+/**
+ * Map of local name -> exported lucide name for a file's lucide imports.
+ * `import { Home as HouseIcon }` means the config's `icon: HouseIcon` is
+ * lucide's `Home`.
+ */
+function parseLucideImports(content) {
+  const imports = new Map()
+
+  for (const match of content.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]lucide-react['"]/g)) {
+    for (const specifier of match[1].split(',')) {
+      const parts = specifier.trim().replace(/^type\s+/, '').split(/\s+as\s+/)
+      const exported = parts[0]?.trim()
+      const local = (parts[1] || parts[0])?.trim()
+      if (exported && local) {
+        imports.set(local, exported)
+      }
+    }
+  }
+
+  return imports
+}
+
+/**
+ * Icon names referenced by a single config file. Exported for tests.
+ */
+export function extractIconNames(content) {
+  const lucideImports = parseLucideImports(content)
+  const names = []
+
+  // `icon: Users` or `'icon': Users` — only counts when the identifier came
+  // from lucide-react
+  for (const match of content.matchAll(/(?:\bicon|['"]icon['"])\s*:\s*([A-Za-z_$][\w$]*)/g)) {
+    const exported = lucideImports.get(match[1])
+    if (exported) {
+      names.push(exported)
+    }
+  }
+
+  // `icon: 'Users'` or `icon: 'pie-chart'` — a theme's sidebar sections and
+  // block configs use both spellings; the caller folds kebab-case into the
+  // lucide export name and validates the result against lucide's export list.
+  for (const match of content.matchAll(/(?:\bicon|['"]icon['"])\s*:\s*['"]([A-Za-z][\w$-]*)['"]/g)) {
+    names.push(match[1])
+  }
+
+  return names
+}
+
+/**
+ * Icon references in a config file that this build cannot turn into a name.
+ * Exported for tests.
+ *
+ * Only a direct named import of lucide-react and a string literal reach the
+ * registry. Anything else — a namespace access (`I.Users`), an identifier
+ * aliased through another module, a component of the project's own — is not
+ * resolvable by reading this file, so it never enters the registry and
+ * resolveIcon falls back. That is silent, hence the warning.
+ */
+export function findUnresolvedIconRefs(content) {
+  const lucideImports = parseLucideImports(content)
+  const unresolved = []
+
+  for (const match of content.matchAll(/(?:\bicon|['"]icon['"])\s*:\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)/g)) {
+    const reference = match[1]
+    const isMember = reference.includes('.')
+
+    if (isMember || !lucideImports.has(reference)) {
+      unresolved.push(reference)
+    }
+  }
+
+  return unresolved
+}
+
+async function collectConfigFiles(dir, matcher, found = []) {
+  if (!existsSync(dir)) {
+    return found
+  }
+
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return found
+  }
+
+  for (const entry of entries) {
+    const entryPath = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      await collectConfigFiles(entryPath, matcher, found)
+    } else if (matcher(entryPath)) {
+      found.push(entryPath)
+    }
+  }
+
+  return found
+}
+
+function coreEntitiesDir(config) {
+  if (config.isNpmMode) {
+    return join(config.projectRoot, 'node_modules/@nextsparkjs/core/src/entities')
+  }
+  if (config.isMonorepoMode && config.monorepoRoot) {
+    return join(config.monorepoRoot, 'packages/core/src/entities')
+  }
+  return join(config.projectRoot, 'packages/core/src/entities')
+}
+
+/**
+ * Discover every icon name the runtime can look up by string.
+ * @param {Array} blocks - Blocks from block discovery (each with an `icon` name)
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {Promise<string[]>} Sorted, de-duplicated, validated icon names
+ */
+export async function discoverIcons(blocks, config) {
+  const candidates = new Set(FALLBACK_ICONS)
+
+  // Only the configs whose icons reach resolveIcon. Widening this would put
+  // icons in the dashboard bundle that nothing can ask for.
+  const iconSources = [
+    ...(await collectConfigFiles(coreEntitiesDir(config), isIconSourcePath)),
+    ...(await collectConfigFiles(config.themesDir, isIconSourcePath)),
+    ...(await collectConfigFiles(config.pluginsDir, isIconSourcePath))
+  ]
+
+  const unresolved = []
+
+  for (const configPath of iconSources) {
+    try {
+      const content = await readFile(configPath, 'utf8')
+      for (const name of extractIconNames(content)) {
+        candidates.add(name)
+      }
+      for (const reference of findUnresolvedIconRefs(content)) {
+        unresolved.push({ configPath, reference })
+      }
+    } catch {
+      verbose(`[icons] Could not read ${configPath}`)
+    }
+  }
+
+  for (const { configPath, reference } of unresolved) {
+    log(
+      `[icons] ${configPath.replace(config.projectRoot, '')}: cannot resolve \`icon: ${reference}\` at build time, so it is not in the registry and will render the fallback. Name it with a string, or import it directly from lucide-react.`,
+      'warning'
+    )
+  }
+
+  for (const block of blocks || []) {
+    if (block.icon) {
+      candidates.add(block.icon)
+    }
+  }
+
+  const known = await readLucideExportNames(config)
+  if (!known) {
+    // Every name becomes a named import, so a kebab-case one would emit
+    // `import { pie-chart }` and break the build. Without lucide's list there
+    // is nothing to fold them against, so they are dropped instead.
+    const importable = [...candidates].filter(name => /^[A-Za-z_$][\w$]*$/.test(name))
+    log('Could not read lucide-react exports; icon registry will include every importable name found', 'warning')
+    return importable.sort()
+  }
+
+  // Configs spell icons both ways: `CheckSquare` in entity configs, `pie-chart`
+  // in a theme's sidebar and block configs. The registry is keyed by the export
+  // name, so kebab-case names are folded into it rather than dropped.
+  const toPascalCase = name =>
+    name
+      .split(/[-_\s]+/)
+      .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+      .join('')
+
+  const valid = []
+  const unknown = []
+  for (const name of candidates) {
+    if (known.has(name)) {
+      valid.push(name)
+      continue
+    }
+    const pascalCased = toPascalCase(name)
+    if (known.has(pascalCased)) {
+      valid.push(pascalCased)
+      continue
+    }
+    unknown.push(name)
+  }
+
+  if (unknown.length > 0) {
+    log(`Icons not exported by lucide-react, skipped: ${[...new Set(unknown)].sort().join(', ')}`, 'warning')
+  }
+
+  verbose(`[icons] ${valid.length} icon(s) referenced by name`)
+  return [...new Set(valid)].sort()
+}

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

@@ -13,6 +13,7 @@ export { discoverCoreEntities } from './core-entities.mjs'
 export { discoverThemes, discoverThemeRouteFiles } from './themes.mjs'
 export { discoverTemplates, discoverThemeTemplates } from './templates.mjs'
 export { discoverBlocks } from './blocks.mjs'
+export { discoverIcons } from './icons.mjs'
 export { discoverMiddlewares } from './middlewares.mjs'
 export { discoverPermissionsConfig } from './permissions.mjs'
 export { discoverAuthConfig } from './auth.mjs'

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

@@ -1,14 +1,61 @@
 /**
  * Block Registry Generator
  *
- * Generates block-registry.ts
+ * Generates block-registry.ts, block-registry.client.ts and block-registry.lazy.ts
+ *
+ * The split is what keeps block components out of the browser bundle. A block
+ * component is a server component and may import server-only code; the editor,
+ * the picker and the devtools viewers are client components that only ever read
+ * the configs. Importing both from one module drags every component — and
+ * whatever it imports — into the client build, which fails outright when one of
+ * them is server-only.
  *
  * @module core/scripts/build/registry/generators/block-registry
  */
 
 import { join } from 'path'
+import { toSafeIdentifier } from './identifier.mjs'
 import { convertCorePath } from '../config.mjs'
 
+/**
+ * The registry entries both halves emit, so the configs cannot drift apart.
+ *
+ * @param {Array} blocks - Discovered blocks
+ * @returns {string} The entries, ready to sit inside the object literal
+ */
+function buildRegistryEntries(blocks) {
+  return blocks.map(block => {
+
+    const slugVar = toSafeIdentifier(block.slug)
+    const scopeValue = block.scope
+      ? `[${block.scope.map(s => `'${s}'`).join(', ')}]`
+      : 'undefined'
+    const examplesValue = block.hasExamples ? `${slugVar}_examples` : '[]'
+    const allowInPatternsValue = block.allowInPatterns !== undefined
+      ? block.allowInPatterns.toString()
+      : 'undefined'
+
+    return `  '${block.slug}': {
+    slug: '${block.slug}',
+    name: '${block.name}',
+    description: '${block.description}',
+    category: '${block.category}' as BlockCategory,
+    icon: '${block.icon}',
+    componentPath: '${block.paths.component}',
+    schemaPath: '${block.paths.schema}',
+    fieldsPath: '${block.paths.fields}',
+    thumbnail: ${block.paths.thumbnail ? `'${block.paths.thumbnail}'` : 'undefined'},
+    fieldDefinitions: ${slugVar}_fields,
+    examples: ${examplesValue},
+    scope: ${scopeValue},
+    allowInPatterns: ${allowInPatternsValue},
+    isCore: false,
+    source: 'theme' as const,
+    sourceId: '${block.themeName}'
+  }`
+  }).join(',\n')
+}
+
 /**
  * Generate the block registry file
  * @param {Array} blocks - Discovered blocks
@@ -56,11 +103,8 @@ type BlockConfig = {
   replacedBy?: string
 }
 
-export const BLOCK_REGISTRY: Record<string, BlockConfig> = {}
-
-export const BLOCK_CATEGORIES: string[] = []
-
-export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<unknown>>> = {}
+export * from './block-registry.client'
+export { BLOCK_COMPONENTS } from './block-registry.lazy'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const BLOCK_COMPONENTS_SSR: Record<string, React.ComponentType<any>> = {}
@@ -80,7 +124,7 @@ export const BLOCK_METADATA = {
   const ssrImports = []
 
   blocks.forEach(block => {
-    const slugVar = block.slug.replace(/-/g, '_')
+    const slugVar = toSafeIdentifier(block.slug)
 
     imports.push(`import { fieldDefinitions as ${slugVar}_fields } from '${block.paths.fields}'`)
     ssrImports.push(`import { default as ${slugVar}_component } from '${block.paths.component}'`)
@@ -93,35 +137,7 @@ export const BLOCK_METADATA = {
   const fieldImports = imports.join('\n')
   const ssrComponentImports = ssrImports.join('\n')
 
-  const registryEntries = blocks.map(block => {
-    const slugVar = block.slug.replace(/-/g, '_')
-    const scopeValue = block.scope
-      ? `[${block.scope.map(s => `'${s}'`).join(', ')}]`
-      : 'undefined'
-    const examplesValue = block.hasExamples ? `${slugVar}_examples` : '[]'
-    const allowInPatternsValue = block.allowInPatterns !== undefined
-      ? block.allowInPatterns.toString()
-      : 'undefined'
-
-    return `  '${block.slug}': {
-    slug: '${block.slug}',
-    name: '${block.name}',
-    description: '${block.description}',
-    category: '${block.category}' as BlockCategory,
-    icon: '${block.icon}',
-    componentPath: '${block.paths.component}',
-    schemaPath: '${block.paths.schema}',
-    fieldsPath: '${block.paths.fields}',
-    thumbnail: ${block.paths.thumbnail ? `'${block.paths.thumbnail}'` : 'undefined'},
-    fieldDefinitions: ${slugVar}_fields,
-    examples: ${examplesValue},
-    scope: ${scopeValue},
-    allowInPatterns: ${allowInPatternsValue},
-    isCore: false,
-    source: 'theme' as const,
-    sourceId: '${block.themeName}'
-  }`
-  }).join(',\n')
+  const registryEntries = buildRegistryEntries(blocks)
 
   const categories = [...new Set(blocks.map(b => b.category))]
 
@@ -139,29 +155,17 @@ export const BLOCK_METADATA = {
  */
 
 import React from 'react'
-import type { BlockConfig, BlockCategory } from '${convertCorePath('@/core/types', outputFilePath, config)}'
 
-${fieldImports}
+// Configs live in the client half so a client component can read them without
+// pulling in a single block component.
+export * from './block-registry.client'
+// Lazy components live in their own module, which a client component can import
+// without the static imports below.
+export { BLOCK_COMPONENTS } from './block-registry.lazy'
 
 // Direct component imports for SSR — zero CLS, synchronous hydration
 ${ssrComponentImports}
 
-export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
-${registryEntries}
-}
-
-export const BLOCK_CATEGORIES: BlockCategory[] = [${categories.map(c => `'${c}'`).join(', ')}]
-
-/**
- * Lazy-loaded block components for client-side rendering (admin UI, block picker).
- * Each component is wrapped with React.lazy for code-splitting.
- */
-export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<any>>> = {
-${blocks.map(block => {
-    return `  '${block.slug}': React.lazy(() => import('${block.paths.component}').then(mod => ({ default: Object.values(mod)[0] as React.ComponentType<any> })))`
-  }).join(',\n')}
-}
-
 /**
  * Direct-imported block components for SSR rendering.
  * Static imports ensure synchronous hydration — zero CLS.
@@ -170,7 +174,7 @@ ${blocks.map(block => {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const BLOCK_COMPONENTS_SSR: Record<string, React.ComponentType<any>> = {
 ${blocks.map(block => {
-    const slugVar = block.slug.replace(/-/g, '_')
+    const slugVar = toSafeIdentifier(block.slug)
     return `  '${block.slug}': ${slugVar}_component`
   }).join(',\n')}
 }
@@ -192,3 +196,147 @@ ${categories.map(cat => {
 }
 `
 }
+
+/**
+ * Generate the client-safe half: block configs, with no component imports.
+ *
+ * This is what a client component reads. Keeping it free of component imports
+ * is the whole point — a block component is a server component, and pulling one
+ * into the client build fails the build when it imports server-only code.
+ *
+ * @param {Array} blocks - Discovered blocks
+ * @param {object} config - Configuration object from getConfig()
+ * @returns {string} Generated TypeScript content
+ */
+export function generateBlockRegistryClient(blocks, config) {
+  const outputFilePath = join(config.outputDir, 'block-registry.client.ts')
+  const header = `/**
+ * Auto-generated Block Registry (client-safe)
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Blocks discovered: ${blocks.length}
+ *
+ * Block configs only: no component imports, so a client component can read the
+ * registry without the block components reaching the browser bundle.
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build-registry.mjs
+ */
+`
+
+  if (blocks.length === 0) {
+    return `${header}
+// Inline type definition for empty registry (avoids import issues in npm mode)
+type BlockConfig = {
+  slug: string
+  name: string
+  description?: string
+  category: string
+  icon?: string
+  componentPath?: string
+  schemaPath?: string
+  fieldsPath?: string
+  thumbnail?: string
+  fieldDefinitions: unknown[]
+  examples: unknown[]
+  scope?: string[]
+  allowInPatterns?: boolean
+  schemaType?: string
+  tags?: string[]
+  isCore?: boolean
+  source?: string
+  sourceId?: string
+  version?: string
+  deprecated?: boolean
+  replacedBy?: string
+}
+
+export const BLOCK_REGISTRY: Record<string, BlockConfig> = {}
+
+export const BLOCK_CATEGORIES: string[] = []
+
+export const BLOCK_METADATA = {
+  totalBlocks: 0,
+  categories: [],
+  blocksByCategory: {},
+  generatedAt: '${new Date().toISOString()}',
+  blocks: []
+}
+`
+  }
+
+  const imports = []
+  blocks.forEach(block => {
+    const slugVar = toSafeIdentifier(block.slug)
+    imports.push(`import { fieldDefinitions as ${slugVar}_fields } from '${block.paths.fields}'`)
+    if (block.hasExamples) {
+      imports.push(`import { examples as ${slugVar}_examples } from '${block.paths.examples}'`)
+    }
+  })
+
+  const registryEntries = buildRegistryEntries(blocks)
+  const categories = [...new Set(blocks.map(b => b.category))]
+
+  return `${header}
+import type { BlockConfig, BlockCategory } from '${convertCorePath('@/core/types', outputFilePath, config)}'
+
+${imports.join('\n')}
+
+export const BLOCK_REGISTRY: Record<string, BlockConfig> = {
+${registryEntries}
+}
+
+export const BLOCK_CATEGORIES: BlockCategory[] = [${categories.map(c => `'${c}'`).join(', ')}]
+
+/**
+ * Block registry metadata
+ */
+export const BLOCK_METADATA = {
+  totalBlocks: ${blocks.length},
+  categories: [${categories.map(c => `'${c}'`).join(', ')}],
+  blocksByCategory: {
+${categories.map(cat => `    '${cat}': ${blocks.filter(b => b.category === cat).length}`).join(',\n')}
+  },
+  generatedAt: '${new Date().toISOString()}',
+  blocks: [${blocks.map(b => `'${b.slug}'`).join(', ')}]
+}
+`
+}
+
+/**
+ * Generate the lazy half: every block component behind React.lazy, and no
+ * static import.
+ *
+ * Client components that render blocks (the editor canvas, pattern previews,
+ * devtools) read this, so each block stays in a chunk of its own and loads
+ * when it is shown. Reaching the components through block-registry.ts instead
+ * carries its static SSR imports along, and with them every block and all a
+ * block imports, into that client component's bundle.
+ *
+ * @param {Array} blocks - Discovered blocks
+ * @returns {string} Generated TypeScript content
+ */
+export function generateBlockRegistryLazy(blocks) {
+  const entries = blocks.map(block =>
+    `  '${block.slug}': React.lazy(() => import('${block.paths.component}').then(mod => ({ default: Object.values(mod)[0] as React.ComponentType<any> })))`
+  ).join(',\n')
+
+  return `/**
+ * Auto-generated Block Registry (lazy components)
+ *
+ * Generated at: ${new Date().toISOString()}
+ * Blocks discovered: ${blocks.length}
+ *
+ * Block components behind React.lazy and nothing imported statically, so a
+ * client component can render blocks while each one stays in its own chunk.
+ *
+ * DO NOT EDIT - This file is auto-generated by scripts/build-registry.mjs
+ */
+
+import React from 'react'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const BLOCK_COMPONENTS: Record<string, React.LazyExoticComponent<React.ComponentType<any>>> = {
+${entries}
+}
+`
+}