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

package/scripts/theme/preset.mjs

@@ -0,0 +1,93 @@
+// Ecosystem preset resolution (task 4.1).
+//
+// A shadcn preset (name, code, or builder URL) is resolved by the *pinned*
+// shadcn CLI inside an isolated staging directory seeded with the consumer's own
+// configuration, using `apply <preset> --only theme,font`. Only the resulting
+// theme tokens and font wiring are read back and merged; the consumer's
+// component files, base/structural style, icon library and import aliases are
+// never touched, and a full `apply` is never run against the live project.
+
+import { cp, mkdtemp, readFile, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { readThemeCss } from './css-theme.mjs'
+import { FONT_VARS, THEME_COLOR_TOKENS } from './tokens.mjs'
+
+// Files copied into staging so shadcn sees the real consumer config. Never the
+// component source — only what theme/font resolution needs.
+const STAGING_FILES = ['package.json', 'components.json', 'tsconfig.json', 'app/globals.css', 'app/layout.tsx']
+
+function slugify(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+// Default runner: stage the consumer config, run the pinned shadcn theme/font
+// application, and let the caller read the staged stylesheet back.
+export function makeShadcnRunner({ shadcnVersion, projectDir, run }) {
+  return async function runPreset(presetRef, stagingDir) {
+    for (const rel of STAGING_FILES) {
+      const from = join(projectDir, rel)
+      if (existsSync(from)) await cp(from, join(stagingDir, rel))
+    }
+    const args = ['dlx', `shadcn@${shadcnVersion}`, 'apply', presetRef, '--only', 'theme,font', '--yes']
+    return run('yarn', args, stagingDir)
+  }
+}
+
+function detectFonts(layout) {
+  const fonts = {}
+  const slots = { sans: 'sans', mono: 'mono', serif: 'serif' }
+  for (const [slot, word] of Object.entries(slots)) {
+    const m = layout.match(new RegExp(`variable:\\s*'--font-([a-z0-9-]+)-${word}'`))
+    if (m) fonts[slot] = { kind: 'google', value: m[1] }
+  }
+  return fonts
+}
+
+/**
+ * Resolve a preset to normalized theme data. Returns
+ * `{ ok: true, tokens, fonts, raw }` or `{ ok: false, diagnostics }`. `runPreset`
+ * is injected so the resolution is testable without network access.
+ */
+export async function resolvePreset(presetRef, { projectDir, runPreset, keepStaging = false }) {
+  const stagingDir = await mkdtemp(join(tmpdir(), `cs-preset-${slugify(presetRef) || 'x'}-`))
+  try {
+    const result = await runPreset(presetRef, stagingDir)
+    if (result && result.status !== 0) {
+      return {
+        ok: false,
+        diagnostics: [
+          {
+            code: 'E_PRESET',
+            severity: 'error',
+            message: `shadcn could not resolve preset "${presetRef}" (exit ${result.status ?? 'unknown'}). Check the name/code/URL and your network.`,
+          },
+        ],
+      }
+    }
+    const globalsPath = join(stagingDir, 'app', 'globals.css')
+    if (!existsSync(globalsPath)) {
+      return {
+        ok: false,
+        diagnostics: [
+          { code: 'E_PRESET', severity: 'error', message: `preset "${presetRef}" produced no app/globals.css in staging` },
+        ],
+      }
+    }
+    const css = await readFile(globalsPath, 'utf8')
+    const tokens = readThemeCss(css)
+    const layoutPath = join(stagingDir, 'app', 'layout.tsx')
+    const fonts = existsSync(layoutPath) ? detectFonts(await readFile(layoutPath, 'utf8')) : {}
+    return { ok: true, tokens, fonts, raw: css }
+  } finally {
+    if (!keepStaging) await rm(stagingDir, { recursive: true, force: true })
+  }
+}
+
+export { spawnSync }

package/scripts/theme/theme-plan.mjs

@@ -0,0 +1,292 @@
+// Theme operation resolution: turn CLI inputs into a validated, deterministic
+// change plan over app/globals.css (visual tokens) and app/layout.tsx (font
+// wiring), then render the resulting files.
+//
+// One operation is resolved in a fixed precedence order (design decision 2):
+//   current state -> imported source -> brand -> primary/accent -> radius/font
+//   shortcuts -> explicit `--set` setters.
+// Later steps win. The plan is computed entirely in memory so a dry-run and a
+// real run share one code path, and a failure leaves the project untouched.
+
+import {
+  bestForeground,
+  contrastRatio,
+  formatOklch,
+  isNamedColor,
+  parseColor,
+  shiftLightness,
+  NAMED_COLOR_NAMES,
+} from './color.mjs'
+import { applyDeclarations, readThemeCss, fillMissingTokens } from './css-theme.mjs'
+import { BRAND_TOKENS, ACCENT_TOKENS, RUNTIME_ONLY_TOKENS, RUNTIME_TOKEN_DEFAULTS, THEME_COLOR_TOKENS } from './tokens.mjs'
+
+const SCOPES = ['light', 'dark', 'shared']
+
+function diagnostic(code, message, extra = {}) {
+  return { code, severity: extra.severity ?? 'error', message, ...extra }
+}
+
+// A `--set` entry: `light.primary=value`, `dark.accent-foreground=value`, or
+// `shared.radius=value`. The token name is written without the leading `--`.
+export function parseSetter(entry) {
+  const eq = entry.indexOf('=')
+  if (eq === -1) return { error: `--set expects <scope>.<token>=<value> (got "${entry}")` }
+  const target = entry.slice(0, eq)
+  const value = entry.slice(eq + 1)
+  const dot = target.indexOf('.')
+  if (dot === -1) return { error: `--set target must be <scope>.<token> (got "${target}")` }
+  const scope = target.slice(0, dot)
+  const name = target.slice(dot + 1)
+  if (!SCOPES.includes(scope)) return { error: `--set scope must be one of ${SCOPES.join(', ')} (got "${scope}")` }
+  if (!name) return { error: `--set is missing a token name (got "${target}")` }
+  if (value === '') return { error: `--set is missing a value (got "${entry}")` }
+  return { scope, name, value }
+}
+
+// Resolve and validate the whole operation before any write. Returns
+// `{ operation, diagnostics }`; a non-empty error diagnostic list means the
+// caller must abort without touching the project.
+export function normalizeOperation(input = {}) {
+  const diagnostics = []
+  const operation = {
+    mode: input.mode ?? null,
+    brand: input.brand ?? null,
+    primary: input.primary ?? null,
+    accent: input.accent ?? null,
+    radius: input.radius ?? null,
+    fontSans: input.fontSans ?? null,
+    fontMono: input.fontMono ?? null,
+    fontSerif: input.fontSerif ?? null,
+    setters: [],
+    preset: input.preset ?? null,
+    presetOnly: input.presetOnly ?? null,
+    importSource: input.importSource ?? null,
+    exportPath: input.exportPath ?? null,
+    dryRun: Boolean(input.dryRun),
+  }
+
+  if (operation.mode !== null && !['light', 'dark', 'system'].includes(operation.mode)) {
+    diagnostics.push(diagnostic('E_MODE', `--mode must be one of light, dark, system (got "${operation.mode}")`))
+  }
+
+  const resolveColor = (label, value) => {
+    if (value === null) return null
+    const parsed = parseColor(value)
+    if (!parsed) {
+      diagnostics.push(
+        diagnostic(
+          'E_COLOR',
+          `--${label} expects a color name (${NAMED_COLOR_NAMES.join(', ')}), a #hex, or an oklch(...) value (got "${value}")`,
+        ),
+      )
+      return null
+    }
+    return parsed
+  }
+  operation.brandColor = resolveColor('brand', operation.brand)
+  operation.primaryColor = resolveColor('primary', operation.primary)
+  operation.accentColor = resolveColor('accent', operation.accent)
+
+  if (operation.radius !== null && !/^(0|\d*\.?\d+)(rem|px|em)$/.test(String(operation.radius))) {
+    diagnostics.push(diagnostic('E_LENGTH', `--radius expects a CSS length such as 0.75rem or 8px (got "${operation.radius}")`))
+  }
+
+  const resolveFont = (label, value) => {
+    if (value === null) return null
+    if (typeof value === 'string' && (value.startsWith('google:') || value.startsWith('system:'))) {
+      const [kind, rest] = [value.slice(0, value.indexOf(':')), value.slice(value.indexOf(':') + 1)]
+      if (!rest.trim()) {
+        diagnostics.push(diagnostic('E_FONT', `--${label} "${kind}:" is missing a ${kind === 'google' ? 'family' : 'stack'}`))
+        return null
+      }
+      return { kind, value: rest.trim() }
+    }
+    diagnostics.push(
+      diagnostic('E_FONT', `--${label} must be google:<Family> or system:<stack> (got "${value}")`),
+    )
+    return null
+  }
+  operation.fonts = {
+    sans: resolveFont('font-sans', operation.fontSans),
+    mono: resolveFont('font-mono', operation.fontMono),
+    serif: resolveFont('font-serif', operation.fontSerif),
+  }
+
+  const seen = new Set()
+  for (const entry of input.sets ?? []) {
+    const parsed = parseSetter(entry)
+    if (parsed.error) {
+      diagnostics.push(diagnostic('E_SET', parsed.error))
+      continue
+    }
+    const key = `${parsed.scope}.${parsed.name}`
+    if (seen.has(key)) {
+      diagnostics.push(diagnostic('E_SET_DUP', `--set assigns ${key} more than once`))
+      continue
+    }
+    seen.add(key)
+    operation.setters.push(parsed)
+  }
+
+  if (operation.presetOnly !== null && operation.preset === null) {
+    diagnostics.push(diagnostic('E_ONLY', '--only requires --preset'))
+  }
+
+  if (operation.exportPath && hasMutation(operation)) {
+    diagnostics.push(diagnostic('E_EXPORT_MIX', '--export cannot be combined with theme mutations; export writes only the export file'))
+  }
+
+  return { operation, diagnostics }
+}
+
+function hasMutation(operation) {
+  return Boolean(
+    operation.mode ||
+      operation.brand ||
+      operation.primary ||
+      operation.accent ||
+      operation.radius ||
+      operation.fontSans ||
+      operation.fontMono ||
+      operation.fontSerif ||
+      operation.setters.length ||
+      operation.preset ||
+      operation.importSource,
+  )
+}
+
+// The primary/brand family derived from one color, per mode.
+export function brandFamily(color, mode) {
+  const fg = bestForeground(color).color
+  const hover = shiftLightness(color, mode === 'light' ? -0.08 : 0.1)
+  const soft = { l: mode === 'light' ? 0.93 : 0.28, c: Math.min(color.c, 0.06), h: color.h }
+  return {
+    primary: formatOklch(color),
+    'primary-foreground': formatOklch(fg),
+    'primary-hover': formatOklch(hover),
+    'primary-soft': formatOklch(soft),
+    ring: formatOklch(color),
+    nav: formatOklch(color),
+  }
+}
+
+export function accentFamily(color) {
+  return {
+    accent: formatOklch(color),
+    'accent-foreground': formatOklch(bestForeground(color).color),
+  }
+}
+
+// Text/background pairs whose contrast the operation should report on.
+const CONTRAST_PAIRS = [
+  ['primary', 'primary-foreground'],
+  ['accent', 'accent-foreground'],
+  ['background', 'foreground'],
+  ['card', 'card-foreground'],
+  ['popover', 'popover-foreground'],
+  ['secondary', 'secondary-foreground'],
+  ['muted', 'muted-foreground'],
+  ['destructive', 'destructive-foreground'],
+  ['promo', 'promo-foreground'],
+]
+
+// Build the change plan for `css` (globals.css content). Returns
+// `{ css, changed, diagnostics, values }`. `changed` lists `scope.token` keys
+// whose value actually changed; `values` is the resolved palette.
+export function planCss(css, operation) {
+  const diagnostics = []
+  const edits = []
+  const push = (scope, name, value) => edits.push({ scope, name, value })
+
+  const modes = ['light', 'dark']
+
+  // Imported source (local CSS export, registry theme or a prior storefront
+  // export) is applied first so brand/primary/accent and explicit setters can
+  // override it.
+  if (operation.importSource) {
+    let imported = null
+    if (operation.importSource.type === 'css') imported = readThemeCss(operation.importSource.css)
+    else if (operation.importSource.type === 'tokens') imported = operation.importSource.tokens
+    if (imported) {
+      for (const mode of modes) {
+        for (const [rawName, value] of Object.entries(imported[mode] ?? {})) {
+          const name = rawName.startsWith('--') ? rawName : `--${rawName}`
+          push(mode, name, value)
+        }
+      }
+    }
+  }
+
+  // Brand / primary: the same color in both modes.
+  const primarySource = operation.brandColor ?? operation.primaryColor
+  if (primarySource) {
+    for (const mode of modes) {
+      const family = brandFamily(primarySource, mode)
+      for (const token of BRAND_TOKENS) push(mode, `--${token}`, family[token])
+    }
+  }
+
+  if (operation.accentColor) {
+    const family = accentFamily(operation.accentColor)
+    for (const mode of modes) for (const token of ACCENT_TOKENS) push(mode, `--${token}`, family[token])
+  }
+
+  if (operation.radius !== null) push('light', '--radius', String(operation.radius))
+
+  // Explicit setters last: they win over shortcuts and imports.
+  for (const setter of operation.setters) {
+    if (setter.scope === 'shared') push('light', `--${setter.name}`, setter.value)
+    else push(setter.scope, `--${setter.name}`, setter.value)
+  }
+
+  let next = applyDeclarations(css, edits)
+
+  // Completeness: the stylesheet owns every runtime token. Fill only what is
+  // absent so an existing (possibly branded) value is never replaced.
+  next = fillMissingTokens(next, [...THEME_COLOR_TOKENS, ...RUNTIME_ONLY_TOKENS], RUNTIME_TOKEN_DEFAULTS)
+
+  // Report measured contrast for the pairs that changed.
+  const before = readThemeCss(css)
+  const after = readThemeCss(next)
+  const changed = []
+  for (const edit of edits) {
+    const scope = edit.scope === 'shared' ? 'light' : edit.scope
+    if (before[scope][edit.name] !== edit.value) changed.push(`${scope}.${edit.name}`)
+  }
+  for (const mode of modes) {
+    for (const [bg, fg] of CONTRAST_PAIRS) {
+      const bgVal = after[mode][`--${bg}`]
+      const fgVal = after[mode][`--${fg}`]
+      if (!bgVal || !fgVal) continue
+      const touched = changed.includes(`${mode}.--${bg}`) || changed.includes(`${mode}.--${fg}`)
+      if (!touched) continue
+      const bgColor = parseColor(bgVal)
+      const fgColor = parseColor(fgVal)
+      if (!bgColor || !fgColor) continue
+      const ratio = contrastRatio(bgColor, fgColor)
+      if (ratio < 4.5) {
+        diagnostics.push(
+          diagnostic('W_CONTRAST', `${mode}: --${bg}/--${fg} contrast is ${ratio.toFixed(2)}:1 (below 4.5:1)`, {
+            severity: 'warning',
+            mode,
+            pair: [bg, fg],
+            ratio: Number(ratio.toFixed(2)),
+          }),
+        )
+      }
+    }
+  }
+
+  return { css: next, changed, diagnostics, values: after }
+}
+
+// High-level: compute the plan for a project's current file contents.
+export function planTheme({ css, operation }) {
+  const { operation: op, diagnostics: opDiagnostics } = normalizeOperation(operation)
+  if (opDiagnostics.some((d) => d.severity === 'error')) {
+    return { ok: false, diagnostics: opDiagnostics }
+  }
+  const planned = planCss(css, op)
+  const diagnostics = [...opDiagnostics, ...planned.diagnostics]
+  return { ok: true, css: planned.css, changed: planned.changed, values: planned.values, diagnostics, operation: op }
+}

package/scripts/theme/tokens.mjs

@@ -0,0 +1,137 @@
+// Token metadata for the theme controls: which tokens the CSS owns, which
+// belong to the brand family, and the geometry/font variables the CLI can edit.
+//
+// RUNTIME_TOKEN_DEFAULTS mirrors @thorprovider/runtime/contracts
+// (theme-tokens.ts). The CLI is a standalone Node program and cannot import the
+// runtime TypeScript, so the values are embedded here exactly as the runtime
+// declares them; `theme-tokens.parity.test.ts` parses the runtime source and
+// fails if the two drift. These values are the *fallback* the scaffold writes
+// when a generated stylesheet is missing a runtime-only token — never an
+// override of a value a developer already set.
+
+// The 29 tokens in the runtime theme contract, in contract order.
+export const THEME_COLOR_TOKENS = [
+  'background', 'foreground', 'card', 'card-foreground', 'popover', 'popover-foreground',
+  'primary', 'primary-foreground', 'primary-hover', 'primary-soft', 'secondary',
+  'secondary-foreground', 'muted', 'muted-foreground', 'accent', 'accent-foreground',
+  'border', 'input', 'ring', 'destructive', 'destructive-foreground', 'nav', 'promo',
+  'promo-foreground', 'stock', 'urgent', 'success', 'warning', 'error',
+]
+
+// Tokens written by a brand/primary/accent change as one coherent family.
+export const BRAND_TOKENS = ['primary', 'primary-foreground', 'primary-hover', 'primary-soft', 'ring', 'nav']
+export const ACCENT_TOKENS = ['accent', 'accent-foreground']
+
+// Geometry + font variables editable through the bounded external surface. The
+// radius scale is derived from a single `--radius` base (shadcn convention).
+export const RADIUS_BASE_VAR = '--radius'
+export const RADIUS_SCALE = { sm: 'calc(var(--radius) - 4px)', md: 'calc(var(--radius) - 2px)', lg: 'var(--radius)', xl: 'calc(var(--radius) + 4px)' }
+export const FONT_VARS = ['--font-sans', '--font-mono', '--font-serif']
+
+export const RUNTIME_TOKEN_DEFAULTS = {
+  light: {
+    background: 'oklch(0.98 0.002 90)',
+    foreground: 'oklch(0.15 0 0)',
+    card: 'oklch(1 0 0)',
+    'card-foreground': 'oklch(0.15 0 0)',
+    popover: 'oklch(1 0 0)',
+    'popover-foreground': 'oklch(0.15 0 0)',
+    primary: 'oklch(0.15 0 0)',
+    'primary-foreground': 'oklch(0.98 0.002 90)',
+    'primary-hover': 'oklch(0.3 0.01 0)',
+    'primary-soft': 'oklch(0.92 0.003 90)',
+    secondary: 'oklch(0.96 0.003 90)',
+    'secondary-foreground': 'oklch(0.15 0 0)',
+    muted: 'oklch(0.94 0.003 90)',
+    'muted-foreground': 'oklch(0.45 0 0)',
+    accent: 'oklch(0.65 0.15 25)',
+    'accent-foreground': 'oklch(1 0 0)',
+    border: 'oklch(0.88 0.003 90)',
+    input: 'oklch(0.92 0.003 90)',
+    ring: 'oklch(0.15 0 0)',
+    destructive: 'oklch(0.55 0.2 25)',
+    'destructive-foreground': 'oklch(1 0 0)',
+    nav: 'oklch(0.15 0 0)',
+    promo: 'oklch(0.8 0.15 45)',
+    'promo-foreground': 'oklch(1 0 0)',
+    stock: 'oklch(0.55 0.18 155)',
+    urgent: 'oklch(0.55 0.2 27)',
+    success: 'oklch(0.55 0.18 155)',
+    warning: 'oklch(0.65 0.16 75)',
+    error: 'oklch(0.55 0.2 27)',
+  },
+  dark: {
+    background: 'oklch(0.145 0 0)',
+    foreground: 'oklch(0.985 0 0)',
+    card: 'oklch(0.145 0 0)',
+    'card-foreground': 'oklch(0.985 0 0)',
+    popover: 'oklch(0.145 0 0)',
+    'popover-foreground': 'oklch(0.985 0 0)',
+    primary: 'oklch(0.985 0 0)',
+    'primary-foreground': 'oklch(0.205 0 0)',
+    'primary-hover': 'oklch(0.85 0.01 0)',
+    'primary-soft': 'oklch(0.269 0 0)',
+    secondary: 'oklch(0.269 0 0)',
+    'secondary-foreground': 'oklch(0.985 0 0)',
+    muted: 'oklch(0.269 0 0)',
+    'muted-foreground': 'oklch(0.708 0 0)',
+    accent: 'oklch(0.269 0 0)',
+    'accent-foreground': 'oklch(0.985 0 0)',
+    border: 'oklch(0.269 0 0)',
+    input: 'oklch(0.269 0 0)',
+    ring: 'oklch(0.439 0 0)',
+    destructive: 'oklch(0.396 0.141 25.723)',
+    'destructive-foreground': 'oklch(0.637 0.237 25.331)',
+    nav: 'oklch(0.985 0 0)',
+    promo: 'oklch(0.6 0.16 45)',
+    'promo-foreground': 'oklch(1 0 0)',
+    stock: 'oklch(0.6 0.14 155)',
+    urgent: 'oklch(0.6 0.18 27)',
+    success: 'oklch(0.6 0.14 155)',
+    warning: 'oklch(0.7 0.14 75)',
+    error: 'oklch(0.6 0.18 27)',
+  },
+}
+
+// The subset that historically lived only in the runtime injection (not in the
+// shadcn-generated stylesheet). The scaffold fills exactly these when absent.
+export const RUNTIME_ONLY_TOKENS = [
+  'primary-hover', 'primary-soft', 'nav', 'promo', 'promo-foreground', 'stock', 'urgent', 'error',
+]
+
+// Every CSS declaration the generated stylesheet must own so the runtime palette
+// injection can be removed without losing a token: the 29 runtime tokens plus the
+// block contract's foreground pairs.
+export const REQUIRED_CSS_TOKENS = [
+  ...THEME_COLOR_TOKENS,
+  'success-foreground',
+  'warning-foreground',
+]
+
+// Fallback values the scaffold fills for a missing required token — never an
+// override of a value already present. Success/warning use the block contract's
+// AA-conformant pair (mirrored by assets/templates/app/app/globals.css), the rest
+// mirror the runtime contract.
+export const DEFAULT_GLOBALS_TOKENS = {
+  light: {
+    ...RUNTIME_TOKEN_DEFAULTS.light,
+    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: {
+    ...RUNTIME_TOKEN_DEFAULTS.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)',
+  },
+}
+
+export function isThemeColorToken(name) {
+  return THEME_COLOR_TOKENS.includes(name)
+}
+
+export const THEME_MODES = ['light', 'dark', 'system']
+export const DEFAULT_THEME_MODE = 'system'

package/scripts/view-assembly.mjs

@@ -153,6 +153,38 @@ function renderEditorialRegistry(entry, def) {
   return `  ${def.elementType}: ${def.registryExport}.${def.elementType},`
 }
 
+// One data-bound instance's element: like an editorial element, but its props
+// merge the user-owned editorial content (`sectionContent[id]`) with the
+// resolved per-instance selection delivered through the view state. The
+// `variant` selects the verified presentation; `products`/`status` are dynamic
+// state refs resolved by json-render, so the server module never fetches or
+// imports the presentation components.
+function renderDataBoundElement(entry, def) {
+  const variant =
+    typeof entry.variant === 'string' && entry.variant.length > 0
+      ? entry.variant
+      : def.defaultVariant
+  if (typeof variant !== 'string' || variant.length === 0) {
+    throw new Error(
+      `Data-bound section "${entry.type}" instance "${entry.id}" has no variant and no declared defaultVariant.`,
+    )
+  }
+  return [
+    `  '${entry.id}': {`,
+    `    type: '${def.elementType}',`,
+    `    props: {`,
+    `      ...(${SECTION_CONTENT_EXPORT}['${entry.id}'] ?? {}),`,
+    `      sectionId: '${entry.id}',`,
+    `      sectionType: '${entry.type}',`,
+    `      variant: '${variant}',`,
+    `      products: { $state: '/sections/${entry.id}/products' },`,
+    `      status: { $state: '/sections/${entry.id}/status' },`,
+    `    },`,
+    `    on: { addClickedToCart: { action: 'addClickedToCart' }, openProduct: { action: 'openProduct' } },`,
+    `  },`,
+  ].join('\n')
+}
+
 /**
  * Assemble a view's derived `index.tsx` and `registry.tsx` from the view's
  * single ordered composition (E3 task 5.1).
@@ -194,8 +226,10 @@ export function assembleView(templateDir, selection = {}, sections = null) {
   const elements = []
   const catalog = []
   const registry = []
+  const registryTypes = new Set()
   const bindings = []
   const slotIds = []
+  const dataBoundIds = []
   const sectionPropsModules = new Set()
   const sectionRegistryImports = new Map()
   for (const entry of ordered) {
@@ -231,11 +265,22 @@ export function assembleView(templateDir, selection = {}, sections = null) {
         `View "${meta.view}" has no editorial fragment for section "${entry.type}".`,
       )
     }
-    elements.push(renderEditorialElement(entry, def))
+    elements.push(
+      def.dataBound === true
+        ? renderDataBoundElement(entry, def)
+        : renderEditorialElement(entry, def),
+    )
     registry.push(renderEditorialRegistry(entry, def))
+    // A registry binding is keyed by the element type, so several instances of
+    // the same section type (for example two `products` sections on one view)
+    // share a single registry entry. Emitting one per instance would produce
+    // duplicate object keys in the derived `registry.tsx`.
+    if (registryTypes.has(def.elementType)) registry.pop()
+    else registryTypes.add(def.elementType)
     slotIds.push(`'${entry.id}'`)
     sectionPropsModules.add(def.propsModule ?? './content')
     sectionRegistryImports.set(def.registryModule, def.registryExport)
+    if (def.dataBound === true) dataBoundIds.push(`'${entry.id}'`)
   }
 
   const indexSkeleton = readFileSync(path.join(assemblyDir(templateDir), 'index.skeleton.tsx'), 'utf8')
@@ -246,6 +291,7 @@ export function assembleView(templateDir, selection = {}, sections = null) {
 
   const index = indexSkeleton
     .replace('@@SECTION_IMPORTS@@', () => renderSectionImports(sectionPropsModules))
+    .replace('@@SECTION_LOADERS@@', () => `[${dataBoundIds.join(', ')}]`)
     .replace('@@ELEMENTS@@', () => elements.join('\n'))
     .replace('@@CATALOG@@', () => catalog.join('\n'))
     .replace('@@SLOT_IDS@@', () => slotIds.join(', '))