@svgrid/create 2.6.0 → 2.8.0

package/index.mjs

@@ -1,466 +1,486 @@
-#!/usr/bin/env node
-// @svgrid/create - scaffold a Svelte app powered by SvGrid.
-//
-//   npm  create @svgrid@latest             # interactive
-//   pnpm create @svgrid                     # interactive
-//   npm  create @svgrid@latest my-app -- --template admin-dashboard
-//   npm  create @svgrid@latest my-app -- -t minimal
-//
-// Zero runtime dependencies - Node built-ins only. Copies a bundled template,
-// renames `_`-prefixed dotfiles, and rewrites the project name.
-
-import { cp, mkdir, readdir, rename, stat, readFile, writeFile } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { dirname, join, basename, resolve, isAbsolute } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { createInterface } from 'node:readline/promises'
-import { stdin, stdout } from 'node:process'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-
-const TEMPLATES = {
-  minimal: {
-    label: 'Minimal      - Vite + Svelte 5 + SvGrid, one page',
-    bundled: join(__dirname, 'templates', 'minimal'),
-  },
-  sveltekit: {
-    label: 'SvelteKit    - server load, URL-driven sort, form-action edits, theme picker',
-    bundled: join(__dirname, 'templates', 'sveltekit'),
-  },
-  'admin-dashboard': {
-    label: 'Admin dashboard - SvelteKit shell, multiple grids, deploy to Vercel',
-    bundled: join(__dirname, 'templates', 'admin-dashboard'),
-    // When running from the monorepo before `prepack` has synced the bundled
-    // copy, fall back to the canonical source.
-    fallback: join(__dirname, '..', '..', 'templates', 'sveltekit-admin-dashboard'),
-  },
-}
-
-const RENAME_BACK = new Map([
-  ['_gitignore', '.gitignore'],
-  ['_npmrc', '.npmrc'],
-  ['_env.example', '.env.example'],
-  ['_package.json', 'package.json'],
-])
-
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  green: '\x1b[32m',
-  cyan: '\x1b[36m',
-  red: '\x1b[31m',
-  yellow: '\x1b[33m',
-}
-const color = stdout.isTTY ? (k, s) => `${c[k]}${s}${c.reset}` : (_k, s) => s
-
-function parseArgs(argv) {
-  const args = { _: [], template: null, force: false, help: false, theme: null, mode: null }
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a === '--help' || a === '-h') args.help = true
-    else if (a === '--force' || a === '-f') args.force = true
-    else if (a === '--template' || a === '-t') args.template = argv[++i]
-    else if (a.startsWith('--template=')) args.template = a.slice('--template='.length)
-    else if (a === '--theme') args.theme = argv[++i]
-    else if (a.startsWith('--theme=')) args.theme = a.slice('--theme='.length)
-    else if (a === '--dark') args.mode = 'dark'
-    else if (a === '--light') args.mode = 'light'
-    else if (!a.startsWith('-')) args._.push(a)
-  }
-  return args
-}
-
-function printHelp() {
-  stdout.write(`
-${color('bold', '@svgrid/create')} - scaffold a Svelte app powered by SvGrid
-
-${color('bold', 'Usage')}
-  npm create @svgrid@latest [dir] -- [--template <name>] [--force]
-
-${color('bold', 'Templates')}
-${Object.entries(TEMPLATES)
-  .map(([k, t]) => `  ${color('cyan', k.padEnd(16))} ${t.label.replace(/^\S+\s+-\s+/, '')}`)
-  .join('\n')}
-
-${color('bold', 'Options')}
-  --theme <id>       One of: ${THEME_IDS.join(', ')} (default: tailwind).
-  --dark / --light   Pin the starting mode. Left out, minimal and sveltekit
-                     follow the visitor's OS; admin-dashboard starts dark.
-  --force            Scaffold into a non-empty directory.
-
-${color('bold', 'Examples')}
-  npm  create @svgrid@latest
-  npm  create @svgrid@latest my-app -- --template admin-dashboard
-  npm  create @svgrid@latest my-app -- -t admin-dashboard --theme material --light
-  pnpm create @svgrid my-app -t minimal
-`)
-}
-
-const THEME_IDS = [
-  'ember', 'shadcn', 'tailwind', 'material', 'excel', 'fluent', 'carbon', 'sap',
-  'salesforce', 'atlassian', 'github', 'antd', 'ag-alpine', 'bootstrap',
-  'vercel', 'linear', 'notion', 'nord', 'dracula', 'catppuccin',
-]
-
-/**
- * Resolve the theme + mode to apply: from `--theme` / `--dark` / `--light`
- * flags, or (in a TTY) an interactive prompt; otherwise left untouched (the
- * template's own default look stands). Reuses `@svgrid/grid/themes`'s own
- * preset list, so the picker can never drift from the canonical set.
- */
-async function promptTheme(args, ask, interactive) {
-  let themes
-  try {
-    themes = await import('@svgrid/grid/themes')
-  } catch {
-    return null // theming is best-effort; the template's own default stands in.
-  }
-
-  let themeId = args.theme ? args.theme.trim().toLowerCase() : null
-  if (themeId && !themes.getThemePreset(themeId)) {
-    stdout.write(`${color('yellow', '!')} Unknown theme "${themeId}" - using tailwind. (${THEME_IDS.join(', ')})\n`)
-    themeId = null
-  }
-  if (!themeId && interactive) {
-    const list = themes.themePresets.map((t, i) => `  ${i + 1}. ${t.name} ${color('dim', `(${t.id})`)}`).join('\n')
-    stdout.write(`\n${color('bold', 'Theme')}\n${list}\n`)
-    const choice = await ask('Pick a number or id:', 'tailwind')
-    const byIndex = themes.themePresets[Number(choice) - 1]
-    themeId = byIndex ? byIndex.id : (themes.getThemePreset(choice.trim().toLowerCase())?.id ?? 'tailwind')
-  }
-  themeId ??= 'tailwind'
-
-  let mode = args.mode
-  if (!mode && interactive) {
-    const a = await ask('Light or dark mode? (light/dark)', 'dark')
-    mode = /^l(ight)?$/i.test(a) ? 'light' : 'dark'
-  }
-  // Whether the mode was actually chosen, as opposed to falling through to the
-  // default below. minimal follows the OS when nobody said, which is only
-  // distinguishable from an explicit --dark by keeping this flag.
-  const explicitMode = mode != null
-  mode ??= 'dark' // matches the template's existing default - only patched when 'light' is chosen.
-
-  return { themeId, mode, explicitMode, name: themes.getThemePreset(themeId)?.name ?? themeId, themes }
-}
-
-/** Rewrite `app.css` between the `svgrid-theme` markers.
- *
- *  The two templates want different things there. admin-dashboard inlines the
- *  resolved `--sg-*` tokens, because its Tailwind layer aliases them to
- *  `--app-*` and having the values on the page makes them editable. minimal
- *  just points at the preset stylesheet the package already ships, which keeps
- *  its `app.css` short enough to read in one go. Which one we are looking at
- *  is decided by what the marked block currently holds, not by the template
- *  name, so a hand-edited project still round-trips. */
-async function applyTheme(destDir, choice) {
-  if (!choice) return
-  const { themeId, themes } = choice
-  const preset = themes.getThemePreset(themeId) ?? themes.defaultThemePreset
-  const light = themes.resolveThemeTokens(preset, 'light')
-  const dark = themes.resolveThemeTokens(preset, 'dark')
-  const block = (selector, tokens, scheme) => {
-    const lines = Object.entries(tokens).map(([k, v]) => `  ${k}: ${v};`).join('\n')
-    return `${selector} {\n${lines}\n  color-scheme: ${scheme};\n}`
-  }
-  const tokenBlocks = `${block(':root', light, 'light')}\n${block(":root[data-theme='dark']", dark, 'dark')}`
-
-  const cssPath = join(destDir, 'src', 'app.css')
-  const cssText = await readFile(cssPath, 'utf8').catch(() => null)
-  if (cssText == null) return
-  const marked = /\/\* svgrid-theme:start \*\/([\s\S]*?)\/\* svgrid-theme:end \*\//
-  // A CSS @import has to stay at the top of the file, so where the block holds
-  // one we swap the preset id in place instead of replacing it with token
-  // declarations that would then sit above the import.
-  const held = cssText.match(marked)
-  const css = held && /@import\s/.test(held[1])
-    ? `@import '@svgrid/grid/themes/${preset.id}.css';`
-    : tokenBlocks
-  if (marked.test(cssText)) {
-    await writeFile(cssPath, cssText.replace(marked, `/* svgrid-theme:start */\n${css}\n/* svgrid-theme:end */`))
-  }
-
-  // Templates with a RUNTIME theme picker keep the starting selection in TS, so
-  // the picker opens on the theme that was scaffolded rather than disagreeing
-  // with the stylesheet above. Absent in templates without a picker, where the
-  // missing file makes this a no-op.
-  const tsPath = join(destDir, 'src', 'lib', 'theme.svelte.ts')
-  const tsText = await readFile(tsPath, 'utf8').catch(() => null)
-  if (tsText == null) return
-  const tsMarked = /\/\* svgrid-initial-theme:start \*\/([\s\S]*?)\/\* svgrid-initial-theme:end \*\//
-  if (!tsMarked.test(tsText)) return
-  // Only the preset here. The mode is left to applyModeSvelteKit, which pins it
-  // only when one was actually asked for.
-  const body = tsText.match(tsMarked)[1].replace(
-    /export const INITIAL_THEME = '[^']*'/,
-    `export const INITIAL_THEME = '${preset.id}'`,
-  )
-  await writeFile(
-    tsPath,
-    tsText.replace(
-      tsMarked,
-      `/* svgrid-initial-theme:start */${body}/* svgrid-initial-theme:end */`,
-    ),
-  )
-}
-
-/** sveltekit settles its start mode in an inline script in `src/app.html`,
- *  falling back to the OS preference, exactly as minimal does. Pin it only when
- *  light or dark was actually asked for. The picker in the layout reads the
- *  attribute that script sets, so both halves have to agree. */
-async function applyModeSvelteKit(destDir, choice) {
-  if (!choice || !choice.explicitMode) return
-
-  const htmlPath = join(destDir, 'src', 'app.html')
-  const html = await readFile(htmlPath, 'utf8').catch(() => null)
-  if (html != null) {
-    await writeFile(
-      htmlPath,
-      html
-        .replace(`<html lang="en" data-theme="light">`, `<html lang="en" data-theme="${choice.mode}">`)
-        .replace(
-          `var fallback = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'`,
-          `var fallback = '${choice.mode}'`,
-        ),
-    )
-  }
-
-  const tsPath = join(destDir, 'src', 'lib', 'theme.svelte.ts')
-  const ts = await readFile(tsPath, 'utf8').catch(() => null)
-  if (ts == null) return
-  await writeFile(
-    tsPath,
-    ts.replace(
-      /export const INITIAL_MODE: ThemeMode = '[^']*'/,
-      `export const INITIAL_MODE: ThemeMode = '${choice.mode}'`,
-    ),
-  )
-}
-
-/** admin-dashboard defaults to dark (see app.html / src/lib/theme.ts /
- *  +layout.svelte). Flip all three to light-by-default when 'light' is chosen
- *  - a no-op when 'dark' is chosen, since that already matches the template. */
-async function applyMode(destDir, choice) {
-  if (!choice || choice.mode !== 'light') return
-
-  const htmlPath = join(destDir, 'src', 'app.html')
-  const html = await readFile(htmlPath, 'utf8').catch(() => null)
-  if (html != null) {
-    await writeFile(
-      htmlPath,
-      html
-        .replace(`data-theme="dark"`, `data-theme="light"`)
-        .replace(`t === 'light' ? 'light' : 'dark'`, `t === 'dark' ? 'dark' : 'light'`),
-    )
-  }
-
-  const themeTsPath = join(destDir, 'src', 'lib', 'theme.ts')
-  const themeTs = await readFile(themeTsPath, 'utf8').catch(() => null)
-  if (themeTs != null) {
-    await writeFile(
-      themeTsPath,
-      themeTs
-        .replace('Defaults to dark (matches app.html).', 'Defaults to light (matches app.html).')
-        .replace(`if (!browser) return 'dark'`, `if (!browser) return 'light'`)
-        .replace(
-          `return localStorage.getItem('theme') === 'light' ? 'light' : 'dark'`,
-          `return localStorage.getItem('theme') === 'dark' ? 'dark' : 'light'`,
-        ),
-    )
-  }
-
-  const layoutPath = join(destDir, 'src', 'routes', '+layout.svelte')
-  const layout = await readFile(layoutPath, 'utf8').catch(() => null)
-  if (layout != null) {
-    await writeFile(
-      layoutPath,
-      layout
-        .replace('// Theme: dark by default (see app.html), toggleable + persisted.', '// Theme: light by default (see app.html), toggleable + persisted.')
-        .replace(`let theme = $state<Theme>('dark')`, `let theme = $state<Theme>('light')`),
-    )
-  }
-}
-
-/** minimal picks its start mode in an inline script in `index.html`, falling
- *  back to the OS preference. Pin it only when light or dark was actually asked
- *  for - following the OS is the better default for anyone who did not say. */
-async function applyModeMinimal(destDir, choice) {
-  if (!choice || !choice.explicitMode) return
-
-  const htmlPath = join(destDir, 'index.html')
-  const html = await readFile(htmlPath, 'utf8').catch(() => null)
-  if (html == null) return
-
-  await writeFile(
-    htmlPath,
-    html
-      .replace(`<html lang="en" data-theme="light">`, `<html lang="en" data-theme="${choice.mode}">`)
-      .replace(
-        `var fallback = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'`,
-        `var fallback = '${choice.mode}'`,
-      ),
-  )
-}
-
-function sanitizeName(name) {
-  return (
-    name
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9._-]+/g, '-')
-      .replace(/^[-_.]+|[-_.]+$/g, '') || 'sv-grid-app'
-  )
-}
-
-function resolveTemplateDir(key) {
-  const t = TEMPLATES[key]
-  if (existsSync(t.bundled)) return t.bundled
-  if (t.fallback && existsSync(t.fallback)) return t.fallback
-  return null
-}
-
-async function copyTemplate(srcDir, destDir) {
-  // Match only on the path RELATIVE to the template root. The absolute `src`
-  // includes the install location (e.g. `.../node_modules/@svgrid/create/...`),
-  // so testing it directly would match `node_modules` and skip the whole copy.
-  const skip = /(^|[\\/])(node_modules|\.svelte-kit|\.vercel|build|dist)([\\/]|$)/
-  await cp(srcDir, destDir, {
-    recursive: true,
-    filter: (src) => !skip.test(src.slice(srcDir.length)),
-  })
-  // Rename `_`-prefixed files back to their real dotfile names.
-  await renameBack(destDir)
-}
-
-async function renameBack(dir) {
-  for (const entry of await readdir(dir)) {
-    const full = join(dir, entry)
-    if ((await stat(full)).isDirectory()) {
-      await renameBack(full)
-    } else if (RENAME_BACK.has(entry)) {
-      await rename(full, join(dir, RENAME_BACK.get(entry)))
-    }
-  }
-}
-
-async function setProjectName(destDir, name) {
-  const pkgPath = join(destDir, 'package.json')
-  if (!existsSync(pkgPath)) return
-  try {
-    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
-    pkg.name = name
-    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
-  } catch {
-    // leave the template's name if it isn't valid JSON for some reason
-  }
-}
-
-async function isEmptyDir(dir) {
-  if (!existsSync(dir)) return true
-  const entries = await readdir(dir)
-  return entries.filter((e) => e !== '.git').length === 0
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2))
-  if (args.help) return printHelp()
-
-  const interactive = stdin.isTTY && stdout.isTTY
-  let rl = null
-  const ask = async (q, def) => {
-    if (!interactive) return def
-    rl ??= createInterface({ input: stdin, output: stdout })
-    const a = (await rl.question(`${q} ${color('dim', `(${def})`)} `)).trim()
-    return a || def
-  }
-
-  stdout.write(`\n${color('bold', '◆ @svgrid/create')}  ${color('dim', 'Svelte + SvGrid')}\n\n`)
-
-  // 1. Target directory.
-  let target = args._[0]
-  if (!target) target = await ask('Project directory:', 'my-sv-grid-app')
-  const destDir = resolve(process.cwd(), target)
-  const projectName = sanitizeName(basename(destDir))
-
-  // 2. Template.
-  let template = args.template
-  if (!template) {
-    if (interactive) {
-      stdout.write(`\n  Templates:\n`)
-      Object.entries(TEMPLATES).forEach(([, t], i) => {
-        stdout.write(`   ${color('cyan', String(i + 1))}. ${t.label}\n`)
-      })
-      const pick = await ask(`\nChoose a template (1-${Object.keys(TEMPLATES).length}):`, '1')
-      template = Object.keys(TEMPLATES)[Number(pick) - 1] ?? 'minimal'
-    } else {
-      template = 'minimal'
-    }
-  }
-  if (!TEMPLATES[template]) {
-    if (rl) rl.close()
-    stdout.write(
-      `\n${color('red', '✖')} Unknown template "${template}". Choose: ${Object.keys(TEMPLATES).join(', ')}\n`,
-    )
-    process.exit(1)
-  }
-
-  // 3. Safety: don't clobber a non-empty directory.
-  if (!(await isEmptyDir(destDir)) && !args.force) {
-    const ok = await ask(
-      `\n${color('yellow', '!')} ${target} is not empty. Continue and overwrite files? (y/N)`,
-      'N',
-    )
-    if (!/^y(es)?$/i.test(ok)) {
-      if (rl) rl.close()
-      stdout.write(`${color('red', '✖')} Aborted.\n`)
-      process.exit(1)
-    }
-  }
-
-  const srcDir = resolveTemplateDir(template)
-  if (!srcDir) {
-    if (rl) rl.close()
-    stdout.write(
-      `\n${color('red', '✖')} Template "${template}" is not available in this build.\n`,
-    )
-    process.exit(1)
-  }
-
-  // 3b. Theme + light/dark mode. Both templates carry the full --sg-* palette
-  // and a toggle, so both get asked.
-  const themeChoice = await promptTheme(args, ask, interactive)
-  if (rl) rl.close()
-
-  // 4. Scaffold.
-  await mkdir(destDir, { recursive: true })
-  await copyTemplate(srcDir, destDir)
-  await setProjectName(destDir, projectName)
-  await applyTheme(destDir, themeChoice)
-  await applyMode(destDir, themeChoice)
-  await applyModeMinimal(destDir, themeChoice)
-  await applyModeSvelteKit(destDir, themeChoice)
-
-  // 5. Next steps.
-  const rel = isAbsolute(target) || target.startsWith('.') ? target : `./${target}`
-  stdout.write(`\n${color('green', '✔')} Scaffolded ${color('bold', projectName)} (${template}) into ${rel}\n`)
-  if (themeChoice) {
-    // minimal and sveltekit only pin a mode when one was asked for; otherwise
-    // they read the OS preference at load, so reporting "dark" here would be a
-    // lie. admin-dashboard is dark by default either way.
-    const pinned = themeChoice.explicitMode || template === 'admin-dashboard'
-    const mode = pinned ? themeChoice.mode : 'follows your OS'
-    stdout.write(`  ${color('dim', 'theme')} ${themeChoice.name} (${mode})\n`)
-  }
-  stdout.write(`\n`)
-  stdout.write(`${color('bold', 'Next steps')}\n`)
-  stdout.write(`  cd ${target}\n`)
-  stdout.write(`  npm install\n`)
-  stdout.write(`  npm run dev\n\n`)
-  stdout.write(`${color('dim', 'Docs:')} https://svgrid.com/docs   ${color('dim', 'Pro:')} https://svgrid.com/pricing\n\n`)
-}
-
-main().catch((err) => {
-  console.error(err)
-  process.exit(1)
-})
+#!/usr/bin/env node
+// @svgrid/create - scaffold a Svelte app powered by SvGrid.
+//
+//   npm  create @svgrid@latest             # interactive
+//   pnpm create @svgrid                     # interactive
+//   npm  create @svgrid@latest my-app -- --template admin-dashboard
+//   npm  create @svgrid@latest my-app -- -t minimal
+//
+// Zero runtime dependencies - Node built-ins only. Copies a bundled template,
+// renames `_`-prefixed dotfiles, and rewrites the project name.
+
+import { cp, mkdir, readdir, rename, stat, readFile, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join, basename, resolve, isAbsolute } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+import { stdin, stdout } from 'node:process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const TEMPLATES = {
+  minimal: {
+    label: 'Minimal      - Vite + Svelte 5 + SvGrid, one page',
+    bundled: join(__dirname, 'templates', 'minimal'),
+  },
+  sveltekit: {
+    label: 'SvelteKit    - server load, URL-driven sort, form-action edits, cookie auth + roles',
+    bundled: join(__dirname, 'templates', 'sveltekit'),
+  },
+  'pivot-dashboard': {
+    label: 'Pivot dashboard - pivot cube + linked chart + drill-through (needs @svgrid/enterprise)',
+    bundled: join(__dirname, 'templates', 'pivot-dashboard'),
+  },
+  'admin-dashboard': {
+    label: 'Admin dashboard - SvelteKit shell, multiple grids, deploy to Vercel',
+    bundled: join(__dirname, 'templates', 'admin-dashboard'),
+    // When running from the monorepo before `prepack` has synced the bundled
+    // copy, fall back to the canonical source.
+    fallback: join(__dirname, '..', '..', 'templates', 'sveltekit-admin-dashboard'),
+  },
+  headless: {
+    label: 'Headless     - createSvGrid engine, your own <table> and CSS',
+    bundled: join(__dirname, 'templates', 'headless'),
+    // No <SvGrid>, so no preset stylesheet and nothing for --theme to write to.
+    // Asking the theme questions here would collect two answers and apply
+    // neither.
+    theme: false,
+  },
+}
+
+const RENAME_BACK = new Map([
+  ['_gitignore', '.gitignore'],
+  ['_npmrc', '.npmrc'],
+  ['_env.example', '.env.example'],
+  ['_package.json', 'package.json'],
+])
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+}
+const color = stdout.isTTY ? (k, s) => `${c[k]}${s}${c.reset}` : (_k, s) => s
+
+function parseArgs(argv) {
+  const args = { _: [], template: null, force: false, help: false, theme: null, mode: null }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') args.help = true
+    else if (a === '--force' || a === '-f') args.force = true
+    else if (a === '--template' || a === '-t') args.template = argv[++i]
+    else if (a.startsWith('--template=')) args.template = a.slice('--template='.length)
+    else if (a === '--theme') args.theme = argv[++i]
+    else if (a.startsWith('--theme=')) args.theme = a.slice('--theme='.length)
+    else if (a === '--dark') args.mode = 'dark'
+    else if (a === '--light') args.mode = 'light'
+    else if (!a.startsWith('-')) args._.push(a)
+  }
+  return args
+}
+
+function printHelp() {
+  stdout.write(`
+${color('bold', '@svgrid/create')} - scaffold a Svelte app powered by SvGrid
+
+${color('bold', 'Usage')}
+  npm create @svgrid@latest [dir] -- [--template <name>] [--force]
+
+${color('bold', 'Templates')}
+${Object.entries(TEMPLATES)
+  .map(([k, t]) => `  ${color('cyan', k.padEnd(16))} ${t.label.replace(/^\S+\s+-\s+/, '')}`)
+  .join('\n')}
+
+${color('bold', 'Options')}
+  --theme <id>       One of: ${THEME_IDS.join(', ')} (default: ember).
+                     Ignored by headless, which ships no stylesheet to theme.
+  --dark / --light   Pin the starting mode. Left out, minimal and sveltekit
+                     follow the visitor's OS; admin-dashboard starts dark.
+  --force            Scaffold into a non-empty directory.
+
+${color('bold', 'Examples')}
+  npm  create @svgrid@latest
+  npm  create @svgrid@latest my-app -- --template admin-dashboard
+  npm  create @svgrid@latest my-app -- -t admin-dashboard --theme material --light
+  pnpm create @svgrid my-app -t minimal
+`)
+}
+
+const THEME_IDS = [
+  'ember', 'shadcn', 'tailwind', 'material', 'excel', 'fluent', 'carbon', 'sap',
+  'salesforce', 'atlassian', 'github', 'antd', 'ag-alpine', 'bootstrap',
+  'vercel', 'linear', 'notion', 'nord', 'dracula', 'catppuccin',
+]
+
+/**
+ * Resolve the theme + mode to apply: from `--theme` / `--dark` / `--light`
+ * flags, or (in a TTY) an interactive prompt; otherwise left untouched (the
+ * template's own default look stands). Reuses `@svgrid/grid/themes`'s own
+ * preset list, so the picker can never drift from the canonical set.
+ */
+async function promptTheme(args, ask, interactive) {
+  let themes
+  try {
+    themes = await import('@svgrid/grid/themes')
+  } catch {
+    return null // theming is best-effort; the template's own default stands in.
+  }
+
+  let themeId = args.theme ? args.theme.trim().toLowerCase() : null
+  if (themeId && !themes.getThemePreset(themeId)) {
+    stdout.write(`${color('yellow', '!')} Unknown theme "${themeId}" - using ember. (${THEME_IDS.join(', ')})\n`)
+    themeId = null
+  }
+  if (!themeId && interactive) {
+    const list = themes.themePresets.map((t, i) => `  ${i + 1}. ${t.name} ${color('dim', `(${t.id})`)}`).join('\n')
+    stdout.write(`\n${color('bold', 'Theme')}\n${list}\n`)
+    const choice = await ask('Pick a number or id:', 'ember')
+    const byIndex = themes.themePresets[Number(choice) - 1]
+    themeId = byIndex ? byIndex.id : (themes.getThemePreset(choice.trim().toLowerCase())?.id ?? 'ember')
+  }
+  themeId ??= 'ember'
+
+  let mode = args.mode
+  if (!mode && interactive) {
+    const a = await ask('Light or dark mode? (light/dark)', 'dark')
+    mode = /^l(ight)?$/i.test(a) ? 'light' : 'dark'
+  }
+  // Whether the mode was actually chosen, as opposed to falling through to the
+  // default below. minimal follows the OS when nobody said, which is only
+  // distinguishable from an explicit --dark by keeping this flag.
+  const explicitMode = mode != null
+  mode ??= 'dark' // matches the template's existing default - only patched when 'light' is chosen.
+
+  return { themeId, mode, explicitMode, name: themes.getThemePreset(themeId)?.name ?? themeId, themes }
+}
+
+/** Rewrite `app.css` between the `svgrid-theme` markers.
+ *
+ *  The two templates want different things there. admin-dashboard inlines the
+ *  resolved `--sg-*` tokens, because its Tailwind layer aliases them to
+ *  `--app-*` and having the values on the page makes them editable. minimal
+ *  just points at the preset stylesheet the package already ships, which keeps
+ *  its `app.css` short enough to read in one go. Which one we are looking at
+ *  is decided by what the marked block currently holds, not by the template
+ *  name, so a hand-edited project still round-trips. */
+async function applyTheme(destDir, choice) {
+  if (!choice) return
+  const { themeId, themes } = choice
+  const preset = themes.getThemePreset(themeId) ?? themes.defaultThemePreset
+  const light = themes.resolveThemeTokens(preset, 'light')
+  const dark = themes.resolveThemeTokens(preset, 'dark')
+  const block = (selector, tokens, scheme) => {
+    const lines = Object.entries(tokens).map(([k, v]) => `  ${k}: ${v};`).join('\n')
+    return `${selector} {\n${lines}\n  color-scheme: ${scheme};\n}`
+  }
+  const tokenBlocks = `${block(':root', light, 'light')}\n${block(":root[data-theme='dark']", dark, 'dark')}`
+
+  const cssPath = join(destDir, 'src', 'app.css')
+  const cssText = await readFile(cssPath, 'utf8').catch(() => null)
+  if (cssText == null) return
+  const marked = /\/\* svgrid-theme:start \*\/([\s\S]*?)\/\* svgrid-theme:end \*\//
+  // A CSS @import has to stay at the top of the file, so where the block holds
+  // one we swap the preset id in place instead of replacing it with token
+  // declarations that would then sit above the import.
+  const held = cssText.match(marked)
+  const css = held && /@import\s/.test(held[1])
+    ? `@import '@svgrid/grid/themes/${preset.id}.css';`
+    : tokenBlocks
+  if (marked.test(cssText)) {
+    await writeFile(cssPath, cssText.replace(marked, `/* svgrid-theme:start */\n${css}\n/* svgrid-theme:end */`))
+  }
+
+  // Templates with a RUNTIME theme picker keep the starting selection in TS, so
+  // the picker opens on the theme that was scaffolded rather than disagreeing
+  // with the stylesheet above. Absent in templates without a picker, where the
+  // missing file makes this a no-op.
+  const tsPath = join(destDir, 'src', 'lib', 'theme.svelte.ts')
+  const tsText = await readFile(tsPath, 'utf8').catch(() => null)
+  if (tsText == null) return
+  const tsMarked = /\/\* svgrid-initial-theme:start \*\/([\s\S]*?)\/\* svgrid-initial-theme:end \*\//
+  if (!tsMarked.test(tsText)) return
+  // Only the preset here. The mode is left to applyModeSvelteKit, which pins it
+  // only when one was actually asked for.
+  const body = tsText.match(tsMarked)[1].replace(
+    /export const INITIAL_THEME = '[^']*'/,
+    `export const INITIAL_THEME = '${preset.id}'`,
+  )
+  await writeFile(
+    tsPath,
+    tsText.replace(
+      tsMarked,
+      `/* svgrid-initial-theme:start */${body}/* svgrid-initial-theme:end */`,
+    ),
+  )
+}
+
+/** sveltekit settles its start mode in an inline script in `src/app.html`,
+ *  falling back to the OS preference, exactly as minimal does. Pin it only when
+ *  light or dark was actually asked for. The picker in the layout reads the
+ *  attribute that script sets, so both halves have to agree. */
+async function applyModeSvelteKit(destDir, choice) {
+  if (!choice || !choice.explicitMode) return
+
+  const htmlPath = join(destDir, 'src', 'app.html')
+  const html = await readFile(htmlPath, 'utf8').catch(() => null)
+  if (html != null) {
+    await writeFile(
+      htmlPath,
+      html
+        .replace(`<html lang="en" data-theme="light">`, `<html lang="en" data-theme="${choice.mode}">`)
+        .replace(
+          `var fallback = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'`,
+          `var fallback = '${choice.mode}'`,
+        ),
+    )
+  }
+
+  const tsPath = join(destDir, 'src', 'lib', 'theme.svelte.ts')
+  const ts = await readFile(tsPath, 'utf8').catch(() => null)
+  if (ts == null) return
+  await writeFile(
+    tsPath,
+    ts.replace(
+      /export const INITIAL_MODE: ThemeMode = '[^']*'/,
+      `export const INITIAL_MODE: ThemeMode = '${choice.mode}'`,
+    ),
+  )
+}
+
+/** admin-dashboard defaults to dark (see app.html / src/lib/theme.ts /
+ *  +layout.svelte). Flip all three to light-by-default when 'light' is chosen
+ *  - a no-op when 'dark' is chosen, since that already matches the template. */
+async function applyMode(destDir, choice) {
+  if (!choice || choice.mode !== 'light') return
+
+  const htmlPath = join(destDir, 'src', 'app.html')
+  const html = await readFile(htmlPath, 'utf8').catch(() => null)
+  if (html != null) {
+    await writeFile(
+      htmlPath,
+      html
+        .replace(`data-theme="dark"`, `data-theme="light"`)
+        .replace(`t === 'light' ? 'light' : 'dark'`, `t === 'dark' ? 'dark' : 'light'`),
+    )
+  }
+
+  const themeTsPath = join(destDir, 'src', 'lib', 'theme.ts')
+  const themeTs = await readFile(themeTsPath, 'utf8').catch(() => null)
+  if (themeTs != null) {
+    await writeFile(
+      themeTsPath,
+      themeTs
+        .replace('Defaults to dark (matches app.html).', 'Defaults to light (matches app.html).')
+        .replace(`if (!browser) return 'dark'`, `if (!browser) return 'light'`)
+        .replace(
+          `return localStorage.getItem('theme') === 'light' ? 'light' : 'dark'`,
+          `return localStorage.getItem('theme') === 'dark' ? 'dark' : 'light'`,
+        ),
+    )
+  }
+
+  const layoutPath = join(destDir, 'src', 'routes', '+layout.svelte')
+  const layout = await readFile(layoutPath, 'utf8').catch(() => null)
+  if (layout != null) {
+    await writeFile(
+      layoutPath,
+      layout
+        .replace('// Theme: dark by default (see app.html), toggleable + persisted.', '// Theme: light by default (see app.html), toggleable + persisted.')
+        .replace(`let theme = $state<Theme>('dark')`, `let theme = $state<Theme>('light')`),
+    )
+  }
+}
+
+/** minimal picks its start mode in an inline script in `index.html`, falling
+ *  back to the OS preference. Pin it only when light or dark was actually asked
+ *  for - following the OS is the better default for anyone who did not say. */
+async function applyModeMinimal(destDir, choice) {
+  if (!choice || !choice.explicitMode) return
+
+  const htmlPath = join(destDir, 'index.html')
+  const html = await readFile(htmlPath, 'utf8').catch(() => null)
+  if (html == null) return
+
+  await writeFile(
+    htmlPath,
+    html
+      .replace(`<html lang="en" data-theme="light">`, `<html lang="en" data-theme="${choice.mode}">`)
+      .replace(
+        `var fallback = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'`,
+        `var fallback = '${choice.mode}'`,
+      ),
+  )
+}
+
+function sanitizeName(name) {
+  return (
+    name
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, '-')
+      .replace(/^[-_.]+|[-_.]+$/g, '') || 'sv-grid-app'
+  )
+}
+
+function resolveTemplateDir(key) {
+  const t = TEMPLATES[key]
+  if (existsSync(t.bundled)) return t.bundled
+  if (t.fallback && existsSync(t.fallback)) return t.fallback
+  return null
+}
+
+async function copyTemplate(srcDir, destDir) {
+  // Match only on the path RELATIVE to the template root. The absolute `src`
+  // includes the install location (e.g. `.../node_modules/@svgrid/create/...`),
+  // so testing it directly would match `node_modules` and skip the whole copy.
+  const skip = /(^|[\\/])(node_modules|\.svelte-kit|\.vercel|build|dist)([\\/]|$)/
+  await cp(srcDir, destDir, {
+    recursive: true,
+    filter: (src) => !skip.test(src.slice(srcDir.length)),
+  })
+  // Rename `_`-prefixed files back to their real dotfile names.
+  await renameBack(destDir)
+}
+
+async function renameBack(dir) {
+  for (const entry of await readdir(dir)) {
+    const full = join(dir, entry)
+    if ((await stat(full)).isDirectory()) {
+      await renameBack(full)
+    } else if (RENAME_BACK.has(entry)) {
+      await rename(full, join(dir, RENAME_BACK.get(entry)))
+    }
+  }
+}
+
+async function setProjectName(destDir, name) {
+  const pkgPath = join(destDir, 'package.json')
+  if (!existsSync(pkgPath)) return
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+    pkg.name = name
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  } catch {
+    // leave the template's name if it isn't valid JSON for some reason
+  }
+}
+
+async function isEmptyDir(dir) {
+  if (!existsSync(dir)) return true
+  const entries = await readdir(dir)
+  return entries.filter((e) => e !== '.git').length === 0
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) return printHelp()
+
+  const interactive = stdin.isTTY && stdout.isTTY
+  let rl = null
+  const ask = async (q, def) => {
+    if (!interactive) return def
+    rl ??= createInterface({ input: stdin, output: stdout })
+    const a = (await rl.question(`${q} ${color('dim', `(${def})`)} `)).trim()
+    return a || def
+  }
+
+  stdout.write(`\n${color('bold', '◆ @svgrid/create')}  ${color('dim', 'Svelte + SvGrid')}\n\n`)
+
+  // 1. Target directory.
+  let target = args._[0]
+  if (!target) target = await ask('Project directory:', 'my-sv-grid-app')
+  const destDir = resolve(process.cwd(), target)
+  const projectName = sanitizeName(basename(destDir))
+
+  // 2. Template.
+  let template = args.template
+  if (!template) {
+    if (interactive) {
+      stdout.write(`\n  Templates:\n`)
+      Object.entries(TEMPLATES).forEach(([, t], i) => {
+        stdout.write(`   ${color('cyan', String(i + 1))}. ${t.label}\n`)
+      })
+      const pick = await ask(`\nChoose a template (1-${Object.keys(TEMPLATES).length}):`, '1')
+      template = Object.keys(TEMPLATES)[Number(pick) - 1] ?? 'minimal'
+    } else {
+      template = 'minimal'
+    }
+  }
+  if (!TEMPLATES[template]) {
+    if (rl) rl.close()
+    stdout.write(
+      `\n${color('red', '✖')} Unknown template "${template}". Choose: ${Object.keys(TEMPLATES).join(', ')}\n`,
+    )
+    process.exit(1)
+  }
+
+  // 3. Safety: don't clobber a non-empty directory.
+  if (!(await isEmptyDir(destDir)) && !args.force) {
+    const ok = await ask(
+      `\n${color('yellow', '!')} ${target} is not empty. Continue and overwrite files? (y/N)`,
+      'N',
+    )
+    if (!/^y(es)?$/i.test(ok)) {
+      if (rl) rl.close()
+      stdout.write(`${color('red', '✖')} Aborted.\n`)
+      process.exit(1)
+    }
+  }
+
+  const srcDir = resolveTemplateDir(template)
+  if (!srcDir) {
+    if (rl) rl.close()
+    stdout.write(
+      `\n${color('red', '✖')} Template "${template}" is not available in this build.\n`,
+    )
+    process.exit(1)
+  }
+
+  // 3b. Theme + light/dark mode - only for templates that render <SvGrid> and
+  // therefore carry a --sg-* palette. headless has no stylesheet to write to,
+  // so it is neither asked nor told a theme; say so if flags implied otherwise.
+  const themed = TEMPLATES[template].theme !== false
+  if (!themed && (args.theme || args.mode)) {
+    stdout.write(
+      `${color('yellow', '!')} ${template} has no stylesheet to theme - ignoring --theme/--dark/--light.\n`,
+    )
+  }
+  const themeChoice = themed ? await promptTheme(args, ask, interactive) : null
+  if (rl) rl.close()
+
+  // 4. Scaffold.
+  await mkdir(destDir, { recursive: true })
+  await copyTemplate(srcDir, destDir)
+  await setProjectName(destDir, projectName)
+  await applyTheme(destDir, themeChoice)
+  await applyMode(destDir, themeChoice)
+  await applyModeMinimal(destDir, themeChoice)
+  await applyModeSvelteKit(destDir, themeChoice)
+
+  // 5. Next steps.
+  const rel = isAbsolute(target) || target.startsWith('.') ? target : `./${target}`
+  stdout.write(`\n${color('green', '✔')} Scaffolded ${color('bold', projectName)} (${template}) into ${rel}\n`)
+  if (themeChoice) {
+    // minimal and sveltekit only pin a mode when one was asked for; otherwise
+    // they read the OS preference at load, so reporting "dark" here would be a
+    // lie. admin-dashboard is dark by default either way.
+    const pinned = themeChoice.explicitMode || template === 'admin-dashboard'
+    const mode = pinned ? themeChoice.mode : 'follows your OS'
+    stdout.write(`  ${color('dim', 'theme')} ${themeChoice.name} (${mode})\n`)
+  }
+  stdout.write(`\n`)
+  stdout.write(`${color('bold', 'Next steps')}\n`)
+  stdout.write(`  cd ${target}\n`)
+  stdout.write(`  npm install\n`)
+  stdout.write(`  npm run dev\n\n`)
+  stdout.write(`${color('dim', 'Docs:')} https://svgrid.com/docs   ${color('dim', 'Pro:')} https://svgrid.com/pricing\n\n`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})