@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/render-templates.mjs

@@ -10,6 +10,15 @@ import { mkdir, readdir, readFile, writeFile, rm } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { buildStateComposer, buildHandlersComposer, buildCompositionComposer, toCamel } from './composers.mjs'
+import { hasViewAssembly, isAssemblyRel, writeViewAssembly } from './view-assembly.mjs'
+import {
+  resolveFeatureMountOverrides,
+  resolveViewGenerationSelection,
+} from './view-selection.mjs'
+import { getFeature } from '../recipes/validate.mjs'
+import { fillMissingTokens } from './theme/css-theme.mjs'
+import { REQUIRED_CSS_TOKENS, DEFAULT_GLOBALS_TOKENS } from './theme/tokens.mjs'
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const pkgRoot = path.resolve(here, '..')
@@ -29,7 +38,17 @@ export function toPascal(value) {
   return value.replace(/(^\w|[-_]\w)/g, (m) => m.replace(/[-_]/, '').toUpperCase())
 }
 
-export function replacePlaceholders(content, { name, siteName }) {
+// Kebab/snake/spaces → Title Case ("my-shop" → "My Shop"). Storefront names are
+// always kebab-cased upstream (toKebab), so separator handling is sufficient.
+export function toTitle(value) {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ')
+}
+
+export function replacePlaceholders(content, { name, siteName, mode = DEFAULT_THEME_MODE }) {
   const camel = toPascal(name)
   const header = content.match(HEADER_RE)?.[1]
   let body = content
@@ -38,24 +57,27 @@ export function replacePlaceholders(content, { name, siteName }) {
     .replaceAll('__STOREFRONT_CAMEL__', camel)
     .replaceAll('__STOREFRONT__', name)
     .replaceAll('__SITE_NAME__', siteName)
+    .replaceAll('__STOREFRONT_MODE__', THEME_MODES.includes(mode) ? mode : DEFAULT_THEME_MODE)
   if (header) {
     body = body.replace('@@HEADER@@', `// Generated by Thor Commerce storefront (template: ${header})`)
   }
   return body
 }
 
-async function walk(root, dir, out) {
+async function walk(root, dir, out, skip) {
   for (const entry of await readdir(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name)
-    if (entry.isDirectory()) await walk(root, full, out)
-    else out.push({ abs: full, rel: path.relative(root, full) })
+    const rel = path.relative(root, full)
+    if (skip && skip(rel)) continue
+    if (entry.isDirectory()) await walk(root, full, out, skip)
+    else out.push({ abs: full, rel })
   }
   return out
 }
 
-export async function renderTree(fromDir, toDir, subs) {
+export async function renderTree(fromDir, toDir, subs, { skip } = {}) {
   await mkdir(toDir, { recursive: true })
-  for (const { abs, rel } of await walk(fromDir, fromDir, [])) {
+  for (const { abs, rel } of await walk(fromDir, fromDir, [], skip)) {
     const dest = path.join(toDir, rel).replaceAll('__STOREFRONT__', subs.name)
     await mkdir(path.dirname(dest), { recursive: true })
     const raw = await readFile(abs, 'utf8')
@@ -63,19 +85,86 @@ export async function renderTree(fromDir, toDir, subs) {
   }
 }
 
-export async function writeBarrel(viewsDir) {
-  const viewNames = (await readdir(viewsDir, { withFileTypes: true }))
-    .filter((e) => e.isDirectory() && existsSync(path.join(viewsDir, e.name, 'index.tsx')))
-    .map((e) => e.name)
-    .sort()
-  const body =
+// A generated export binding must be a valid JS identifier. View and feature
+// names are kebab-case (`static-pages`), so their binding is the camelCase form
+// (`staticPages`). A name that cannot yield a valid binding is rejected before
+// any derived file is written.
+export function isValidIdentifier(value) {
+  return typeof value === 'string' && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value)
+}
+
+// Reserved words cannot be an import binding, so a view named after one (the
+// `static` view) binds as `<name>View` (`staticView`) — the name its module
+// exports. Non-reserved names are unchanged, so existing barrels are stable.
+const RESERVED_BINDING_NAMES = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+  'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+  'finally', 'for', 'function', 'if', 'implements', 'import', 'in', 'instanceof',
+  'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public',
+  'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
+  'var', 'void', 'while', 'with', 'yield',
+])
+
+function viewBinding(name) {
+  const identifier = toCamel(name)
+  return RESERVED_BINDING_NAMES.has(identifier) ? `${identifier}View` : identifier
+}
+
+// Build the views barrel from the manifest's installed view names — never by
+// scanning leftover directories, so a view removed from the manifest cannot
+// reappear. `viewNames` may be strings or `{ name }` objects. Throws when a
+// name cannot yield a valid export identifier, so the caller rejects the
+// composition before writing anything.
+export function buildBarrel(viewNames) {
+  const names = viewNames.map((view) => (typeof view === 'string' ? view : view.name)).sort()
+  const entries = names.map((name) => {
+    const identifier = viewBinding(name)
+    if (!isValidIdentifier(identifier)) {
+      throw new Error(`View "${name}" does not yield a valid export identifier ("${identifier}").`)
+    }
+    return { name, identifier }
+  })
+  return (
     `// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/views/index.ts)\n` +
-    `// View registry (barrel). A freshly scaffolded store registers only \`home\`.\n` +
+    `// View registry (barrel), generated from the manifest's installed views.\n` +
     `// Adding a view appends one import and one entry here; shared files never change.\n\n` +
     `import type { ViewModule } from './types'\n` +
-    viewNames.map((v) => `import { ${v} } from './${v}'`).join('\n') +
-    `\n\nexport const views: ViewModule[] = [${viewNames.join(', ')}]\n`
-  await writeFile(path.join(viewsDir, 'index.ts'), body)
+    entries.map((entry) => `import { ${entry.identifier} } from './${entry.name}'`).join('\n') +
+    `\n\nexport const views: ViewModule[] = [${entries.map((entry) => entry.identifier).join(', ')}]\n`
+  )
+}
+
+export async function writeBarrel(viewsDir, viewNames) {
+  await writeFile(path.join(viewsDir, 'index.ts'), buildBarrel(viewNames))
+}
+
+// The client-side counterpart of the view barrel. The server barrel
+// (`views/index.ts`) exposes each `ViewModule`, whose `loader` is server-only;
+// importing it from a Client Component would drag the loaders into the client
+// graph. This barrel imports only each view's client `registry` mapping, so the
+// generated shell registry never pulls server loaders.
+export function buildClientRegistryBarrel(viewNames) {
+  const names = viewNames.map((view) => (typeof view === 'string' ? view : view.name)).sort()
+  const entries = names.map((name) => {
+    const identifier = viewBinding(name)
+    if (!isValidIdentifier(identifier)) {
+      throw new Error(`View "${name}" does not yield a valid export identifier ("${identifier}").`)
+    }
+    return { name, identifier }
+  })
+  return (
+    `'use client'\n\n` +
+    `// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/views/registry.ts)\n` +
+    `// Client view-registry barrel, generated from the manifest's installed views.\n` +
+    `// Imports only each view's client mapping, never its loader-bearing module.\n\n` +
+    `import type { ViewRegistry } from './types'\n` +
+    entries.map((entry) => `import { registry as ${entry.identifier}Registry } from './${entry.name}/registry'`).join('\n') +
+    `\n\nexport const viewRegistries: ViewRegistry[] = [${entries.map((entry) => `${entry.identifier}Registry`).join(', ')}]\n`
+  )
+}
+
+export async function writeClientRegistryBarrel(viewsDir, viewNames) {
+  await writeFile(path.join(viewsDir, 'registry.ts'), buildClientRegistryBarrel(viewNames))
 }
 
 // The storefront's required markers inside app/layout.tsx and app/globals.css.
@@ -87,52 +176,48 @@ const LAYOUT_MARKER = '@thorprovider/runtime/host-glue/providers'
 // scaffolder must still detect the injection as present (cross-version
 // idempotency) instead of duplicating the provider block.
 const LEGACY_LAYOUT_MARKER = '@thorprovider/storefronts/host-glue/providers'
+// Marks the next-themes ThemeProvider wiring. Kept distinct from the provider
+// marker so both injections compose independently (either may be added first)
+// and so a mode change can be re-applied without touching the provider block.
+const THEME_MODE_MARKER = "from 'next-themes'"
+export const THEME_MODES = ['light', 'dark', 'system']
+export const DEFAULT_THEME_MODE = 'system'
 const GLOBALS_IMPORT = '@import "@thorprovider/blocks/styles.css";'
-const GLOBALS_TOKENS_MARKER = '--success:'
+// Marks the block color bridge in the `@theme inline` block. The success/warning
+// *values* are filled as ordinary declarations (DEFAULT_GLOBALS_TOKENS) so the
+// fill step and the bridge stay in sync.
+const GLOBALS_THEME_MARKER = '--color-success:'
 
-// The block token contract the scaffold guarantees on top of whatever the shadcn
-// preset produced. Values mirror assets/templates/app/app/globals.css (success /
-// warning AA-conformant pairs in both modes); only these tokens are added, never
-// a re-statement of the preset's own tokens.
-const BLOCK_TOKEN_APPEND = `@theme inline {
+// The `@theme inline` bridge the scaffold guarantees on top of whatever the
+// shadcn preset produced, so Tailwind utilities (`bg-success`, `text-warning`, …)
+// resolve against the block tokens. Appended once; never a re-statement of the
+// preset's own tokens.
+const BLOCK_THEME_APPEND = `@theme inline {
   --color-success: var(--success);
   --color-success-foreground: var(--success-foreground);
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
-}
-
-:root {
-  --success: oklch(0.47 0.14 155);
-  --success-foreground: oklch(0.98 0.01 155);
-  --warning: oklch(0.55 0.18 75);
-  --warning-foreground: oklch(0.98 0.02 75);
-}
-
-.dark {
-  --success: oklch(0.6 0.13 155);
-  --success-foreground: oklch(0.1 0.02 155);
-  --warning: oklch(0.7 0.15 75);
-  --warning-foreground: oklch(0.1 0.02 75);
-}
-`
+}`
 
 /**
  * Idempotently inject the storefront provider wiring into an existing
- * app/layout.tsx (the create-next-app default). Adds the imports and themeCss
- * const after the last import line, then wraps {children} in the provider.
- * Returns the content unchanged when the provider marker is already present
- * (so a re-run never duplicates the injection and user edits survive).
+ * app/layout.tsx (the create-next-app default). Adds the provider and registry
+ * imports after the last import line, then wraps {children} in the provider.
+ *
+ * The provider is given NO `themeCss`: a generated single-tenant storefront owns
+ * its theme in app/globals.css, so nothing is injected late in the document to
+ * override it. A host that needs a runtime palette passes `themeCss` explicitly
+ * (see StorefrontProvider). Returns the content unchanged when the provider
+ * marker is already present (so a re-run never duplicates the injection and user
+ * edits survive).
  */
 export function injectLayout(content, name) {
   if (content.includes(LAYOUT_MARKER) || content.includes(LEGACY_LAYOUT_MARKER)) return content
 
   const importLines = [
     `import { StorefrontProvider } from '${LAYOUT_MARKER}'`,
-    `import { themeVarsToCss, themeTokensToVars } from '@thorprovider/runtime/render-core/theme'`,
-    `import { DEFAULT_THEME_TOKENS } from '@thorprovider/runtime/contracts'`,
     `import { registry } from '@/lib/${name}/registry'`,
   ]
-  const constLine = 'const themeCss = themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))'
 
   const lines = content.split('\n')
   let lastImport = -1
@@ -141,26 +226,127 @@ export function injectLayout(content, name) {
   }
   let out
   if (lastImport >= 0) {
-    lines.splice(lastImport + 1, 0, '', ...importLines, '', constLine)
+    lines.splice(lastImport + 1, 0, '', ...importLines)
     out = lines.join('\n')
   } else {
-    out = [...importLines, '', constLine, '', content].join('\n')
+    out = [...importLines, '', content].join('\n')
   }
 
   if (!/\{children\}/.test(out)) return out
   out = out.replace(
     /\{children\}/,
-    '<StorefrontProvider themeCss={themeCss} registry={registry}>{children}</StorefrontProvider>',
+    '<StorefrontProvider registry={registry}>{children}</StorefrontProvider>',
   )
   return out
 }
 
+// The exact default theme expression the previous scaffold injected. Migration
+// removes it so the stylesheet becomes the single visual source.
+const LEGACY_THEME_EXPR = 'themeVarsToCss(themeTokensToVars(DEFAULT_THEME_TOKENS))'
+const LEGACY_THEME_IMPORT = `import { themeVarsToCss, themeTokensToVars } from '@thorprovider/runtime/render-core/theme'`
+const LEGACY_TOKENS_IMPORT = `import { DEFAULT_THEME_TOKENS } from '@thorprovider/runtime/contracts'`
+
 /**
- * Idempotently append the blocks stylesheet import and the block token contract
- * to an existing app/globals.css (produced by create-next-app + shadcn init).
- * The @import is inserted after the last leading @import line; the success /
- * warning tokens are appended at the end. Returns the content unchanged when
- * the blocks import is already present and the success tokens exist.
+ * Migrate the recognized default-palette injection out of an existing
+ * app/layout.tsx so app/globals.css owns the theme. Removes only the known
+ * runtime imports, the known `const themeCss = …DEFAULT_THEME_TOKENS…` line and
+ * the `themeCss={themeCss}` attribute.
+ *
+ * Returns `{ content, changed, migrated, conflict }`. When the file injects a
+ * *custom* themeCss expression (an unrecognized palette), it reports `conflict`
+ * and returns the content unchanged — the CLI never guesses away a developer's
+ * own injection. A file already CSS-owned (no `themeCss`) is returned unchanged.
+ */
+export function migrateLayoutInjection(content) {
+  const result = { content, changed: false, migrated: false, conflict: null }
+  if (!content.includes(LAYOUT_MARKER)) return result
+  if (!/themeCss/.test(content)) return result
+
+  const hasDefaultExpr = content.includes(`const themeCss = ${LEGACY_THEME_EXPR}`)
+  const hasThemeImport = content.includes(LEGACY_THEME_IMPORT)
+  if (!hasDefaultExpr || !hasThemeImport) {
+    result.conflict =
+      'app/layout.tsx injects a custom `themeCss` palette that the CLI does not recognize. ' +
+      'Remove the `themeCss` prop (theme now lives in app/globals.css) or migrate it by hand, then re-run.'
+    return result
+  }
+
+  const next = content
+    .replace(`${LEGACY_THEME_IMPORT}\n`, '')
+    .replace(`${LEGACY_TOKENS_IMPORT}\n`, '')
+    .replace(/^\s*const themeCss = themeVarsToCss\(themeTokensToVars\(DEFAULT_THEME_TOKENS\)\)\n/m, '')
+    .replace(/themeCss=\{themeCss\}\s*/g, '')
+  result.content = next
+  result.changed = next !== content
+  result.migrated = true
+  return result
+}
+
+/**
+ * Idempotently wire the next-themes ThemeProvider into app/layout.tsx so the
+ * scaffolded site can render light/dark/system. `attribute="class"` matches the
+ * `.dark` custom variant in globals.css; `enableSystem` is on so a `system` mode
+ * follows the visitor's OS preference. next-themes injects a blocking script
+ * that sets the class before first paint, which is what prevents the flash.
+ *
+ * The mode is a *site* setting, not a visitor toggle: there is deliberately no
+ * switcher. Changing it is a deterministic rewrite (see `storefront theme`).
+ * Returns the content unchanged when the wiring is already present and the mode
+ * matches, so a re-run or a no-op mode change never rewrites the file.
+ */
+export function injectThemeMode(content, mode = DEFAULT_THEME_MODE) {
+  const resolved = THEME_MODES.includes(mode) ? mode : DEFAULT_THEME_MODE
+  const wrapped = `{children}`
+
+  if (content.includes(THEME_MODE_MARKER)) {
+    // Already wired: only rewrite the mode when it differs (idempotent).
+    const patched = content.replace(
+      /(<ThemeProvider[^>]*defaultTheme=")[^"]*(")/,
+      `$1${resolved}$2`,
+    )
+    return patched
+  }
+
+  const importLine = `import { ThemeProvider } from 'next-themes'`
+  const lines = content.split('\n')
+  let lastImport = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith('import ')) lastImport = i
+  }
+  let out
+  if (lastImport >= 0) {
+    lines.splice(lastImport + 1, 0, importLine)
+    out = lines.join('\n')
+  } else {
+    out = `${importLine}\n${content}`
+  }
+
+  if (!out.includes(wrapped)) return out
+  // next-themes sets the class on <html> during hydration; suppress the
+  // server/client attribute mismatch warning on the root element.
+  if (!/suppressHydrationWarning/.test(out)) {
+    out = out.replace(/<html\b([^>]*)>/, '<html$1 suppressHydrationWarning>')
+  }
+  // ThemeProvider must sit OUTSIDE StorefrontProvider so it controls the class
+  // on <html> independently of the theme tokens. When the provider block is
+  // present, wrap that whole block; otherwise wrap the bare {children}.
+  const providerBlock = /<StorefrontProvider\b[\s\S]*?<\/StorefrontProvider>/
+  const open = `<ThemeProvider attribute="class" defaultTheme="${resolved}" enableSystem>`
+  if (providerBlock.test(out)) {
+    return out.replace(providerBlock, (block) => `${open}${block}</ThemeProvider>`)
+  }
+  return out.replace(wrapped, `${open}{children}</ThemeProvider>`)
+}
+
+/**
+ * Idempotently complete an existing app/globals.css (produced by create-next-app
+ * + shadcn init): append the blocks stylesheet import, append the block color
+ * bridge (`@theme inline`), and fill every missing required token declaration in
+ * `:root` / `.dark` from DEFAULT_GLOBALS_TOKENS. Existing declarations are never
+ * replaced — a developer's customized value always wins — so the generated
+ * stylesheet is the complete, single source of the theme (the runtime palette
+ * injection is no longer emitted). Returns the content unchanged when nothing is
+ * missing.
  */
 export function injectGlobals(content) {
   const lines = content.split('\n')
@@ -178,8 +364,11 @@ export function injectGlobals(content) {
     out = `${GLOBALS_IMPORT}\n${content}`
   }
 
-  if (out.includes(GLOBALS_TOKENS_MARKER)) return out
-  return `${out.replace(/\s*$/, '')}\n\n${BLOCK_TOKEN_APPEND}`
+  if (!out.includes(GLOBALS_THEME_MARKER)) {
+    out = `${out.replace(/\s*$/, '')}\n\n${BLOCK_THEME_APPEND}\n`
+  }
+
+  return fillMissingTokens(out, REQUIRED_CSS_TOKENS, DEFAULT_GLOBALS_TOKENS)
 }
 
 /**
@@ -191,31 +380,110 @@ export function injectGlobals(content) {
  * Removes the template-owned surfaces (and the create-next-app default page)
  * first so repeated runs stay clean and no stage deletes another's output.
  */
-export async function renderScaffold({ targetDir, name, siteName }) {
-  const viewsDir = path.join(targetDir, 'lib', name, 'views')
-  await rm(path.join(targetDir, 'lib', name), { recursive: true, force: true })
+export async function renderScaffold({
+  targetDir,
+  name,
+  siteName,
+  mode = DEFAULT_THEME_MODE,
+  views = ['home'],
+  features = [],
+}) {
+  // `views` accepts a bare name or a manifest view entry (`{ name, intents?,
+  // variants? }`) so the fresh scaffold and a later reconcile read explicit
+  // selections through the same resolver. `features` likewise accepts a bare
+  // name or `{ name, config }`. Resolve every assembled view's selection,
+  // including feature mount overrides, before the first write, so an invalid
+  // selection fails the whole scaffold instead of leaving a partial tree.
+  const viewEntries = views.map((view) => (typeof view === 'string' ? { name: view } : view))
+  const featureEntries = features.map((feature) =>
+    typeof feature === 'string' ? { name: feature, config: {} } : feature,
+  )
+  const mountOverrides = resolveFeatureMountOverrides({ features: featureEntries })
+  if (!mountOverrides.ok) {
+    throw new Error(`Invalid feature config/mount: ${mountOverrides.errors.join(' ')}`)
+  }
+  const viewSelections = new Map()
+  for (const entry of viewEntries) {
+    const viewSrc = path.join(templatesRoot, 'views', entry.name)
+    if (!existsSync(viewSrc) || !hasViewAssembly(viewSrc)) continue
+    const resolved = resolveViewGenerationSelection(entry, mountOverrides.byView)
+    if (!resolved.ok) {
+      throw new Error(
+        `Invalid selection for view "${entry.name}": ${resolved.errors.join(' ')}`,
+      )
+    }
+    viewSelections.set(entry.name, resolved)
+  }
+
+  const libDir = path.join(targetDir, 'lib', name)
+  const viewsDir = path.join(libDir, 'views')
+  await rm(libDir, { recursive: true, force: true })
   await rm(path.join(targetDir, 'app', '[[...slug]]'), { recursive: true, force: true })
   await rm(path.join(targetDir, 'app', 'page.tsx'), { force: true })
 
-  await renderTree(path.join(templatesRoot, 'app', 'app', '[[...slug]]'), path.join(targetDir, 'app', '[[...slug]]'), { name, siteName })
-  await renderTree(path.join(templatesRoot, 'app', 'lib'), path.join(targetDir, 'lib'), { name, siteName })
-  await renderTree(path.join(templatesRoot, 'views'), viewsDir, { name, siteName })
-  await writeBarrel(viewsDir)
+  await renderTree(path.join(templatesRoot, 'app', 'app', '[[...slug]]'), path.join(targetDir, 'app', '[[...slug]]'), { name, siteName, mode })
+  await renderTree(path.join(templatesRoot, 'app', 'lib'), path.join(targetDir, 'lib'), { name, siteName, mode })
+  for (const entry of viewEntries) {
+    const viewSrc = path.join(templatesRoot, 'views', entry.name)
+    if (!existsSync(viewSrc)) continue
+    const assembled = hasViewAssembly(viewSrc)
+    // Assembly sources are authoring input; the derived index.tsx/registry.tsx
+    // are composed from the selected fragments, never copied verbatim.
+    const skip = (rel) => {
+      const normalized = rel.split(path.sep).join('/')
+      if (isAssemblyRel(rel)) return true
+      return assembled && (normalized === 'index.tsx' || normalized === 'registry.tsx')
+    }
+    await renderTree(viewSrc, path.join(viewsDir, entry.name), { name, siteName, mode }, { skip })
+    if (assembled) {
+      const resolved = viewSelections.get(entry.name)
+      await writeViewAssembly({
+        viewDir: path.join(viewsDir, entry.name),
+        templateDir: viewSrc,
+        selection: resolved?.selection ?? {},
+        sections: resolved?.sections ?? null,
+        render: (source) => replacePlaceholders(source, { name, siteName, mode }),
+      })
+    }
+  }
+  for (const feature of featureEntries) {
+    const featureSrc = path.join(templatesRoot, 'features', feature.name)
+    if (existsSync(featureSrc)) await renderTree(featureSrc, path.join(libDir, 'features', feature.name), { name, siteName, mode })
+  }
+  await writeBarrel(viewsDir, viewEntries)
+  await writeClientRegistryBarrel(viewsDir, viewEntries)
+  const featureNames = featureEntries.map((feature) => feature.name)
+  const stateFeatures = featureNames.filter((n) => (getFeature(n)?.state?.length ?? 0) > 0)
+  const handlerFeatures = featureNames.filter((n) => (getFeature(n)?.handlers?.length ?? 0) > 0)
+  await writeFile(path.join(libDir, 'state.ts'), buildStateComposer(stateFeatures))
+  await writeFile(path.join(libDir, 'handlers.ts'), buildHandlersComposer(handlerFeatures))
+  await writeFile(path.join(libDir, 'composition.ts'), buildCompositionComposer(featureEntries, viewEntries))
 
-  await ensureLayoutAppend(targetDir, name, siteName)
+  await ensureLayoutAppend(targetDir, name, siteName, mode)
   await ensureGlobalsAppend(targetDir, name, siteName)
+  await renderRootAgentsMd(targetDir, { name, siteName, mode })
+}
+
+// The managed root guidance file ships with the scaffold: rendered from the
+// package template with the project placeholders, exactly as reconcile renders
+// it, so a fresh scaffold and a later sync agree byte-for-byte.
+async function renderRootAgentsMd(targetDir, subs) {
+  const templatePath = path.join(templatesRoot, 'AGENTS.md')
+  if (!existsSync(templatePath)) return
+  const raw = await readFile(templatePath, 'utf8')
+  await writeFile(path.join(targetDir, 'AGENTS.md'), replacePlaceholders(raw, subs))
 }
 
-async function ensureLayoutAppend(targetDir, name, siteName) {
+async function ensureLayoutAppend(targetDir, name, siteName, mode = DEFAULT_THEME_MODE) {
   const layoutPath = path.join(targetDir, 'app', 'layout.tsx')
   const templatePath = path.join(templatesRoot, 'app', 'app', 'layout.tsx')
   if (!existsSync(layoutPath)) {
     const raw = await readFile(templatePath, 'utf8')
-    await writeFile(layoutPath, replacePlaceholders(raw, { name, siteName }))
+    await writeFile(layoutPath, injectThemeMode(replacePlaceholders(raw, { name, siteName }), mode))
     return
   }
   const existing = await readFile(layoutPath, 'utf8')
-  const injected = injectLayout(existing, name)
+  const injected = injectThemeMode(injectLayout(existing, name), mode)
   if (injected !== existing) await writeFile(layoutPath, injected)
 }
 
@@ -224,7 +492,9 @@ async function ensureGlobalsAppend(targetDir, name, siteName) {
   const templatePath = path.join(templatesRoot, 'app', 'app', 'globals.css')
   if (!existsSync(globalsPath)) {
     const raw = await readFile(templatePath, 'utf8')
-    await writeFile(globalsPath, replacePlaceholders(raw, { name, siteName }))
+    // Run the completeness fill on the fallback template too, so a fresh project
+    // and a shadcn-generated one end with the same required token set.
+    await writeFile(globalsPath, injectGlobals(replacePlaceholders(raw, { name, siteName })))
     return
   }
   const existing = await readFile(globalsPath, 'utf8')
@@ -241,7 +511,7 @@ if (invokedDirectly) {
   }
   const target = path.resolve(process.cwd(), targetArg)
   const name = toKebab(process.argv[3] ?? path.basename(target))
-  const siteName = name
+  const siteName = toTitle(name)
   if (!existsSync(templatesRoot)) {
     console.error(`templates not found: ${templatesRoot}`)
     process.exit(1)

package/scripts/schema-validate.mjs

@@ -0,0 +1,132 @@
+// Minimal, dependency-free validator for the JSON Schema subset used by the
+// published storefront schemas. It supports exactly the keywords those schemas
+// use (type, required, properties, items, additionalProperties, minLength,
+// enum) so a document is validated against the same artifact the package
+// publishes, with no duplicated hand-rolled shape contract.
+
+// Validation keywords this validator understands. Annotation-only keywords are
+// allowed through without affecting the result. Any other keyword is reported
+// as unsupported so a future schema cannot silently be treated as valid.
+const VALIDATION_KEYWORDS = new Set([
+  'type',
+  'enum',
+  'minLength',
+  'required',
+  'properties',
+  'additionalProperties',
+  'items',
+])
+// `default` is an annotation: it documents a field's default value but does not
+// affect validation. Feature config contracts use it so `normalizeConfig` can
+// apply declared defaults without a second source of truth.
+const ANNOTATION_KEYWORDS = new Set(['$schema', '$id', 'title', 'description', 'default'])
+const SUPPORTED_KEYWORDS = new Set([...VALIDATION_KEYWORDS, ...ANNOTATION_KEYWORDS])
+
+function typeOf(value) {
+  if (Array.isArray(value)) return 'array'
+  if (value === null) return 'null'
+  return typeof value
+}
+
+function isObject(value) {
+  return typeOf(value) === 'object'
+}
+
+// Own-property lookup: inherited keys (`constructor`, `__proto__`, `toString`)
+// must never be mistaken for declared schema properties or present data, or an
+// `additionalProperties` constraint could be bypassed.
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+// Walk the schema itself (independent of any value) so an unsupported keyword
+// anywhere in the tree fails clearly instead of being ignored.
+function collectUnsupportedKeywords(schema, path, errors) {
+  if (!isObject(schema)) return
+  for (const keyword of Object.keys(schema)) {
+    if (!SUPPORTED_KEYWORDS.has(keyword)) {
+      errors.push(`${path || 'manifest'} uses an unsupported schema keyword "${keyword}".`)
+    }
+  }
+  const properties = isObject(schema.properties) ? schema.properties : {}
+  for (const key of Object.keys(properties)) {
+    collectUnsupportedKeywords(properties[key], `${path || 'manifest'}.${key}`, errors)
+  }
+  if (isObject(schema.items)) {
+    collectUnsupportedKeywords(schema.items, `${path || 'manifest'}[]`, errors)
+  }
+  if (isObject(schema.additionalProperties)) {
+    collectUnsupportedKeywords(schema.additionalProperties, `${path || 'manifest'}.*`, errors)
+  }
+}
+
+export function validateSchemaSupported(schema) {
+  const errors = []
+  collectUnsupportedKeywords(schema, '', errors)
+  return errors
+}
+
+/**
+ * Validate `value` against `schema`, returning a list of human-readable errors.
+ * Each error is prefixed with the dotted path of the offending field (the root
+ * uses `manifest`), so callers can name the bad input precisely.
+ */
+export function validateAgainstSchema(value, schema, path = '') {
+  const errors = []
+  const label = path || 'manifest'
+
+  if (!isObject(schema)) {
+    errors.push(`${label} uses an invalid schema (expected an object).`)
+    return errors
+  }
+
+  // The schema tree is checked once, at the root, so unsupported keywords fail
+  // closed regardless of which fields the value happens to contain.
+  if (!path) errors.push(...validateSchemaSupported(schema))
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+    if (!types.includes(typeOf(value))) {
+      errors.push(`${label} must be of type ${types.join(' | ')}.`)
+      return errors
+    }
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${label} must be one of: ${schema.enum.join(', ')}.`)
+  }
+
+  if (
+    typeof value === 'string' &&
+    typeof schema.minLength === 'number' &&
+    value.length < schema.minLength
+  ) {
+    errors.push(`${label} must be at least ${schema.minLength} character(s).`)
+  }
+
+  if (isObject(value)) {
+    for (const key of schema.required ?? []) {
+      if (!hasOwn(value, key)) errors.push(`${label} is missing required property "${key}".`)
+    }
+    const properties = isObject(schema.properties) ? schema.properties : {}
+    const additional = schema.additionalProperties
+    for (const key of Object.keys(value)) {
+      const childPath = path ? `${path}.${key}` : key
+      if (hasOwn(properties, key)) {
+        errors.push(...validateAgainstSchema(value[key], properties[key], childPath))
+      } else if (isObject(additional)) {
+        errors.push(...validateAgainstSchema(value[key], additional, childPath))
+      } else if (additional === false) {
+        errors.push(`${label} has unknown property "${key}".`)
+      }
+    }
+  }
+
+  if (Array.isArray(value) && isObject(schema.items)) {
+    value.forEach((item, index) => {
+      errors.push(...validateAgainstSchema(item, schema.items, `${path}[${index}]`))
+    })
+  }
+
+  return errors
+}