@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/scripts/reconcile.mjs

@@ -10,6 +10,7 @@ import {
   buildClientRegistryBarrel,
   writeClientRegistryBarrel,
   injectLayout,
+  migrateLayoutInjection,
   injectThemeMode,
   injectGlobals,
 } from './render-templates.mjs'
@@ -80,18 +81,22 @@ async function renderDerivedTree(fromDir, toDir, subs, classifyRel, changed, ski
 async function ensureLayoutAppend(targetDir, name, siteName, mode, dryRun) {
   const layoutPath = path.join(targetDir, 'app', 'layout.tsx')
   if (!existsSync(layoutPath)) {
-    if (dryRun) return true
+    if (dryRun) return { changed: true, conflict: null }
     const raw = await readFile(path.join(templatesRoot, 'app', 'app', 'layout.tsx'), 'utf8')
     const content = injectThemeMode(replacePlaceholders(raw, { name, siteName, mode }), mode)
     await mkdir(path.dirname(layoutPath), { recursive: true })
     await writeFile(layoutPath, content)
-    return true
+    return { changed: true, conflict: null }
   }
   const existing = await readFile(layoutPath, 'utf8')
-  const content = injectThemeMode(injectLayout(existing, name), mode)
-  if (content === existing) return false
+  // Migrate the recognized default-palette injection (CSS owns the theme now).
+  // A custom injection is reported as a conflict and nothing is written.
+  const migration = migrateLayoutInjection(existing)
+  if (migration.conflict) return { changed: false, conflict: migration.conflict }
+  const content = injectThemeMode(injectLayout(migration.content, name), mode)
+  if (content === existing) return { changed: false, conflict: null }
   if (!dryRun) await writeFile(layoutPath, content)
-  return true
+  return { changed: true, conflict: null }
 }
 
 async function ensureGlobalsAppend(targetDir, name, siteName, dryRun) {
@@ -99,8 +104,9 @@ async function ensureGlobalsAppend(targetDir, name, siteName, dryRun) {
   if (!existsSync(globalsPath)) {
     if (dryRun) return true
     const raw = await readFile(path.join(templatesRoot, 'app', 'app', 'globals.css'), 'utf8')
+    const content = injectGlobals(replacePlaceholders(raw, { name, siteName }))
     await mkdir(path.dirname(globalsPath), { recursive: true })
-    await writeFile(globalsPath, replacePlaceholders(raw, { name, siteName }))
+    await writeFile(globalsPath, content)
     return true
   }
   const existing = await readFile(globalsPath, 'utf8')
@@ -137,7 +143,12 @@ async function pruneEmptyDirs(dir) {
 // template (unknown) are preserved, and their locations are returned so the
 // caller can report them. A pristine template file is removed so a pure
 // add/remove round-trip restores the tree exactly.
-export async function removeViewFiles(projectDir, manifest, viewName, { dryRun = false } = {}) {
+export async function removeViewFiles(
+  projectDir,
+  manifest,
+  viewName,
+  { dryRun = false, legacyDerivedFiles = null } = {},
+) {
   const name = manifest.name
   const viewDir = path.join(projectDir, 'lib', name, 'views', viewName)
   if (!existsSync(viewDir)) return { removed: [], preserved: [] }
@@ -147,6 +158,11 @@ export async function removeViewFiles(projectDir, manifest, viewName, { dryRun =
     mode: manifest.theme?.mode ?? DEFAULT_THEME_MODE,
   }
   const templateDir = viewTemplateDir(viewName)
+  // A retired view's template no longer exists, so its old derived files would
+  // otherwise be treated as unknown and preserved. An explicit bounded list
+  // marks exactly those derived files as known (and therefore removable); a
+  // user-owned or unknown file is still preserved by the class check below.
+  const legacySet = new Set(Array.isArray(legacyDerivedFiles) ? legacyDerivedFiles : [])
   const removed = []
   const preserved = []
   for (const rel of await walkFiles(viewDir)) {
@@ -154,7 +170,7 @@ export async function removeViewFiles(projectDir, manifest, viewName, { dryRun =
     const posixRel = rel.split(path.sep).join('/')
     const fileClass = classifyFile(path.posix.join('views', viewName, posixRel))
     const templatePath = templateDir ? path.join(templateDir, rel) : null
-    const known = Boolean(templatePath && existsSync(templatePath))
+    const known = Boolean((templatePath && existsSync(templatePath)) || legacySet.has(posixRel))
     const maybeAuthored = !known || fileClass === 'user-owned'
     if (maybeAuthored) {
       let pristine = false
@@ -312,7 +328,8 @@ export async function reconcile(projectDir, manifest, { dryRun = false } = {}) {
       return (
         normalized.endsWith('views/index.ts') ||
         normalized === '__STOREFRONT__/state.ts' ||
-        normalized === '__STOREFRONT__/handlers.ts'
+        normalized === '__STOREFRONT__/handlers.ts' ||
+        normalized === '__STOREFRONT__/composition.ts'
       )
     },
     dryRun,
@@ -442,7 +459,11 @@ export async function reconcile(projectDir, manifest, { dryRun = false } = {}) {
     changed.push(clientBarrelPath)
   }
 
-  if (await ensureLayoutAppend(projectDir, name, siteName, mode, dryRun)) {
+  const layoutResult = await ensureLayoutAppend(projectDir, name, siteName, mode, dryRun)
+  if (layoutResult.conflict) {
+    return { ok: false, errors: [layoutResult.conflict], views: [], changed: [] }
+  }
+  if (layoutResult.changed) {
     changed.push(path.join(projectDir, 'app', 'layout.tsx'))
   }
   if (await ensureGlobalsAppend(projectDir, name, siteName, dryRun)) {
@@ -454,6 +475,23 @@ export async function reconcile(projectDir, manifest, { dryRun = false } = {}) {
     }
   }
 
+  // The managed root guidance file is derived: rendered from the package
+  // template with the project placeholders, refreshed by sync, and reported as
+  // drift by doctor's dry-run. It is never seeded-and-frozen (not user-owned),
+  // so the rules a store enforces always match the installed CLI generation.
+  if (classifyFile('AGENTS.md') === 'derived') {
+    const agentsTemplate = path.join(templatesRoot, 'AGENTS.md')
+    if (existsSync(agentsTemplate)) {
+      const agentsPath = path.join(projectDir, 'AGENTS.md')
+      const nextAgents = replacePlaceholders(await readFile(agentsTemplate, 'utf8'), subs)
+      const prevAgents = existsSync(agentsPath) ? await readFile(agentsPath, 'utf8') : null
+      if (prevAgents !== nextAgents) {
+        if (!dryRun) await writeFile(agentsPath, nextAgents)
+        changed.push(agentsPath)
+      }
+    }
+  }
+
   // Composer files are generated from the installed features, not templated.
   // A feature contributes to a composer only when the registry declares it owns
   // state/handlers for it; a pure editorial feature (no state, no handlers)
@@ -463,7 +501,7 @@ export async function reconcile(projectDir, manifest, { dryRun = false } = {}) {
   for (const [composerPath, content] of [
     [path.join(projectDir, 'lib', name, 'state.ts'), buildStateComposer(stateFeatures)],
     [path.join(projectDir, 'lib', name, 'handlers.ts'), buildHandlersComposer(handlerFeatures)],
-    [path.join(projectDir, 'lib', name, 'composition.ts'), buildCompositionComposer(manifest.features)],
+    [path.join(projectDir, 'lib', name, 'composition.ts'), buildCompositionComposer(manifest.features, manifest.views)],
   ]) {
     const prev = existsSync(composerPath) ? await readFile(composerPath, 'utf8') : null
     if (prev === content) continue

package/scripts/render-templates.mjs

@@ -17,6 +17,8 @@ import {
   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, '..')
@@ -84,8 +86,8 @@ export async function renderTree(fromDir, toDir, subs, { skip } = {}) {
 }
 
 // A generated export binding must be a valid JS identifier. View and feature
-// names are kebab-case (`user-panel`), so their binding is the camelCase form
-// (`userPanel`). A name that cannot yield a valid binding is rejected before
+// 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)
@@ -181,51 +183,41 @@ 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:'
-
-// 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 {
+// 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 `@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
@@ -234,20 +226,62 @@ 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'`
+
+/**
+ * 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
@@ -305,11 +339,14 @@ export function injectThemeMode(content, mode = DEFAULT_THEME_MODE) {
 }
 
 /**
- * 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.
+ * 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')
@@ -327,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)
 }
 
 /**
@@ -417,10 +457,21 @@ export async function renderScaffold({
   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))
+  await writeFile(path.join(libDir, 'composition.ts'), buildCompositionComposer(featureEntries, viewEntries))
 
   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, mode = DEFAULT_THEME_MODE) {
@@ -441,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')

package/scripts/section-config.mjs

@@ -0,0 +1,253 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// User-owned source configuration audit.
+//
+// Data-bound section instances (for example the `products` type) resolve their
+// content from a canonical query the user declares in a user-owned `data.ts`
+// export named `sectionSources`. The manifest records only the structural
+// instance (`{ id, type, variant }`); the query lives in the user file. `sync`
+// never patches user files, so a freshly added instance is intentionally
+// unconfigured until the user supplies its entry. `doctor` reports those gaps
+// with the file and instance id so the repair is actionable.
+//
+// The audit is a conservative static read of the object literal: it extracts
+// the top-level keys of `sectionSources` and whether each value is an object.
+// It never executes the user file and never rewrites it. Deep validity (the
+// canonical query fields) is enforced at build/runtime by the runtime
+// `sectionSourceSchema`, which surfaces an `unconfigured` state for the
+// instance rather than failing the page.
+
+/** Locate the `sectionSources` declaration and return the index of its name. */
+function findSectionSourcesIndex(source) {
+  const match = /\bsectionSources\b/.exec(source)
+  return match ? match.index : -1
+}
+
+/**
+ * Match the brace that opens at `open` and return the index of its closer,
+ * ignoring braces inside string literals and comments. Returns -1 when
+ * unbalanced.
+ */
+function matchBrace(source, open) {
+  let depth = 0
+  let i = open
+  while (i < source.length) {
+    const ch = source[i]
+    if (ch === '/' && source[i + 1] === '/') {
+      i = source.indexOf('\n', i)
+      if (i < 0) return -1
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end < 0) return -1
+      i = end + 2
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      i = skipString(source, i)
+      if (i < 0) return -1
+      continue
+    }
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+    i++
+  }
+  return -1
+}
+
+/** Advance past a string literal starting at `start`; returns the index after it. */
+function skipString(source, start) {
+  const quote = source[start]
+  let i = start + 1
+  while (i < source.length) {
+    if (source[i] === '\\') {
+      i += 2
+      continue
+    }
+    if (source[i] === quote) return i + 1
+    i++
+  }
+  return -1
+}
+
+/** Advance past a value starting at `start`, returning the index at depth 0 after it. */
+function skipValue(source, start) {
+  let depth = 0
+  let i = start
+  while (i < source.length) {
+    const ch = source[i]
+    if (ch === '/' && source[i + 1] === '/') {
+      const nl = source.indexOf('\n', i)
+      if (nl < 0) return source.length
+      i = nl + 1
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end < 0) return source.length
+      i = end + 2
+      continue
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const next = skipString(source, i)
+      if (next < 0) return source.length
+      i = next
+      continue
+    }
+    if (ch === '{' || ch === '[' || ch === '(') depth++
+    else if (ch === '}' || ch === ']' || ch === ')') {
+      if (depth === 0) return i
+      depth--
+    } else if (ch === ',' && depth === 0) return i
+    i++
+  }
+  return source.length
+}
+
+/** Read an object key at `start` (quoted string or bare identifier). */
+function readKey(source, start) {
+  const ch = source[start]
+  if (ch === '"' || ch === "'" || ch === '`') {
+    const end = skipString(source, start)
+    if (end < 0) return null
+    return { key: source.slice(start + 1, end - 1), next: end }
+  }
+  let i = start
+  while (i < source.length && /[A-Za-z0-9_$]/.test(source[i])) i++
+  if (i === start) return null
+  return { key: source.slice(start, i), next: i }
+}
+
+function skipWhitespaceAndComments(source, start) {
+  let i = start
+  while (i < source.length) {
+    const ch = source[i]
+    if (/\s/.test(ch)) {
+      i++
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '/') {
+      const nl = source.indexOf('\n', i)
+      if (nl < 0) return source.length
+      i = nl + 1
+      continue
+    }
+    if (ch === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end < 0) return source.length
+      i = end + 2
+      continue
+    }
+    break
+  }
+  return i
+}
+
+/**
+ * Extract the top-level entries of the `sectionSources` object literal in a
+ * `data.ts` source. Returns a Map of key -> `{ objectValue }` (whether the
+ * declared value is an object literal). An absent or unparsable declaration
+ * yields an empty Map.
+ */
+export function extractSectionSourceEntries(source) {
+  const entries = new Map()
+  if (typeof source !== 'string') return entries
+  const declIndex = findSectionSourcesIndex(source)
+  if (declIndex < 0) return entries
+  const bodyStart = source.indexOf('{', declIndex)
+  if (bodyStart < 0) return entries
+  const bodyEnd = matchBrace(source, bodyStart)
+  if (bodyEnd < 0) return entries
+  const body = source.slice(bodyStart + 1, bodyEnd)
+  let i = 0
+  while (i < body.length) {
+    i = skipWhitespaceAndComments(body, i)
+    if (i >= body.length) break
+    const key = readKey(body, i)
+    if (!key) break
+    const colon = skipWhitespaceAndComments(body, key.next)
+    if (body[colon] !== ':') break
+    const valueStart = skipWhitespaceAndComments(body, colon + 1)
+    entries.set(key.key, { objectValue: body[valueStart] === '{' })
+    i = skipValue(body, valueStart)
+    if (body[i] === ',') i++
+  }
+  return entries
+}
+
+/**
+ * The data-bound section instances declared across a manifest's views, in
+ * order. `isDataBound` is the predicate that identifies a data-bound type
+ * (typically `sectionIsDataBound` from `recipes/validate.mjs`).
+ */
+export function collectDataBoundInstances(manifest, isDataBound) {
+  const instances = []
+  const views = Array.isArray(manifest?.views) ? manifest.views : []
+  for (const view of views) {
+    const sections = Array.isArray(view?.sections) ? view.sections : []
+    for (const section of sections) {
+      if (!section || typeof section.type !== 'string') continue
+      if (!isDataBound(section.type)) continue
+      instances.push({
+        view: view.name,
+        id: section.id,
+        type: section.type,
+        variant: typeof section.variant === 'string' ? section.variant : null,
+      })
+    }
+  }
+  return instances
+}
+
+/**
+ * Audit a project's user-owned source configuration against its data-bound
+ * section instances. Returns `{ diagnostics }` where each diagnostic carries
+ * the owning view, the instance id/type, the user-owned file, and a repair
+ * message. Missing declarations and non-object declarations are both reported;
+ * deep query validity is enforced at build/runtime, not here.
+ */
+export function auditSectionConfig({ dir, manifest, isDataBound }) {
+  const diagnostics = []
+  const name = typeof manifest?.name === 'string' && manifest.name.length > 0 ? manifest.name : 'storefront'
+  const instances = collectDataBoundInstances(manifest, isDataBound)
+  const byView = new Map()
+  for (const instance of instances) {
+    if (!byView.has(instance.view)) byView.set(instance.view, [])
+    byView.get(instance.view).push(instance)
+  }
+  for (const [view, viewInstances] of byView) {
+    const relPath = `lib/${name}/views/${view}/data.ts`
+    const absPath = join(dir, relPath)
+    const entries = existsSync(absPath)
+      ? extractSectionSourceEntries(readFileSync(absPath, 'utf8'))
+      : null
+    for (const instance of viewInstances) {
+      const entry = entries?.get(instance.id)
+      if (!entry) {
+        diagnostics.push({
+          code: 'E_SECTION_CONFIG_MISSING',
+          view,
+          id: instance.id,
+          type: instance.type,
+          path: relPath,
+          message: `section "${instance.id}" (${instance.type}) is not configured; add a sectionSources["${instance.id}"] entry in ${relPath}`,
+        })
+      } else if (!entry.objectValue) {
+        diagnostics.push({
+          code: 'E_SECTION_CONFIG_INVALID',
+          view,
+          id: instance.id,
+          type: instance.type,
+          path: relPath,
+          message: `sectionSources["${instance.id}"] in ${relPath} must be an object literal (kind/query/maxItems)`,
+        })
+      }
+    }
+  }
+  return { diagnostics }
+}

package/scripts/starter.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Initial composition for `storefront create`.
+//
+// Without `--starter`, create seeds the minimal baseline (home + cart, no
+// features). With `--starter`, it seeds the full curated set: every curated
+// feature and every curated view — including the views a feature owns, so each
+// installed feature satisfies the composition contract. The set is derived from
+// the registry (`recipes/validate.mjs`), never a hand-maintained list, so held
+// units are excluded by construction.
+
+import { curatedViewNames, starterComposition } from '../recipes/validate.mjs'
+
+export function scaffoldComposition({ starter = false } = {}) {
+  if (!starter) return { views: ['home', 'cart'], features: [] }
+  const { features } = starterComposition()
+  return { views: curatedViewNames(), features }
+}