@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/theme/color.mjs

@@ -0,0 +1,185 @@
+// Color parsing, conversion and contrast for the theme controls.
+//
+// Dependency rationale (design decision 3): no CSS/color parser is present in
+// this package or the workspace, and the storefront CLI pins an exact candidate
+// toolset for generated consumers. Adding a color dependency would churn that
+// pinned candidate for a boundary the CLI already owns, so the small, fully
+// specified OKLCH <-> sRGB math lives here instead. It is deterministic,
+// network-free and has no runtime dependencies.
+//
+// Conversions follow the standard OKLab formulation (Björn Ottosson) with the
+// sRGB transfer function, so a value round-trips and contrast ratios match what
+// a browser computes.
+
+const clamp01 = (value) => Math.min(1, Math.max(0, value))
+const toDeg = (rad) => (rad * 180) / Math.PI
+const toRad = (deg) => (deg * Math.PI) / 180
+
+// sRGB transfer functions (gamma <-> linear).
+function srgbToLinear(channel) {
+  return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+}
+function linearToSrgb(channel) {
+  return channel <= 0.0031308 ? channel * 12.92 : 1.055 * channel ** (1 / 2.4) - 0.055
+}
+
+// OKLCH -> linear sRGB (unclamped; out-of-gamut channels are reported as-is).
+export function oklchToLinearSrgb({ l, c, h }) {
+  const hRad = toRad(h)
+  const a = c * Math.cos(hRad)
+  const b = c * Math.sin(hRad)
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b
+  const lc = l_ ** 3
+  const mc = m_ ** 3
+  const sc = s_ ** 3
+  return {
+    r: 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc,
+    g: -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc,
+    b: -0.0041960863 * lc - 0.7034186147 * mc + 1.707614701 * sc,
+  }
+}
+
+export function linearSrgbToOklch({ r, g, b }) {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+  const c = Math.sqrt(A * A + B * B)
+  let h = toDeg(Math.atan2(B, A))
+  if (h < 0) h += 360
+  return { l: L, c, h }
+}
+
+export function oklchToSrgb({ l, c, h }) {
+  const lin = oklchToLinearSrgb({ l, c, h })
+  return { r: linearToSrgb(lin.r), g: linearToSrgb(lin.g), b: linearToSrgb(lin.b) }
+}
+
+export function srgbToOklch({ r, g, b }) {
+  return linearSrgbToOklch({ r: srgbToLinear(r), g: srgbToLinear(g), b: srgbToLinear(b) })
+}
+
+// Relative luminance (WCAG) from an OKLCH color, computed in linear sRGB.
+export function relativeLuminance({ l, c, h }) {
+  const lin = oklchToLinearSrgb({ l, c, h })
+  return 0.2126 * clamp01(lin.r) + 0.7152 * clamp01(lin.g) + 0.0722 * clamp01(lin.b)
+}
+
+// WCAG contrast ratio between two OKLCH colors (>= 1).
+export function contrastRatio(a, b) {
+  const la = relativeLuminance(a)
+  const lb = relativeLuminance(b)
+  const hi = Math.max(la, lb)
+  const lo = Math.min(la, lb)
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+const WHITE = { l: 1, c: 0, h: 0 }
+const BLACK = { l: 0, c: 0, h: 0 }
+
+// Pick the readable foreground (black or white) for a background by measured
+// contrast rather than an OKLCH lightness threshold. Returns the chosen color
+// and the ratio it achieves.
+export function bestForeground(background) {
+  const onWhite = contrastRatio(background, WHITE)
+  const onBlack = contrastRatio(background, BLACK)
+  return onWhite >= onBlack
+    ? { color: { ...WHITE }, ratio: onWhite }
+    : { color: { ...BLACK }, ratio: onBlack }
+}
+
+// A slightly darker (light mode) / lighter (dark mode) variant for hover states.
+export function shiftLightness({ l, c, h }, delta) {
+  return { l: clamp01(l + delta), c, h }
+}
+
+function round(value, digits) {
+  const factor = 10 ** digits
+  return Math.round(value * factor) / factor
+}
+
+// Canonical CSS output. L keeps 4 significant decimals, C 3, H 2 (no trailing
+// zeros beyond the rounding), matching the hand-authored token style.
+export function formatOklch({ l, c, h }) {
+  const L = round(clamp01(l), 4)
+  const C = round(Math.max(0, c), 4)
+  let H = round(((h % 360) + 360) % 360, 2)
+  if (H === 360) H = 0
+  return `oklch(${L} ${C} ${H})`
+}
+
+// Parse `oklch(L C H [/ A])`. Accepts L as a fraction (0-1) or a percentage.
+export function parseOklch(input) {
+  const match = /^oklch\(\s*([\d.]+%?)\s+([\d.]+%?)\s+([\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+%?))?\s*\)$/i.exec(
+    input.trim(),
+  )
+  if (!match) return null
+  const parseL = (token) => (token.endsWith('%') ? parseFloat(token) / 100 : parseFloat(token))
+  const l = parseL(match[1])
+  const c = match[2].endsWith('%') ? (parseFloat(match[2]) / 100) * 0.4 : parseFloat(match[2])
+  const h = parseFloat(match[3])
+  if ([l, c, h].some((n) => Number.isNaN(n))) return null
+  return { l, c, h }
+}
+
+export function parseHex(input) {
+  const match = /^#([0-9a-f]{3,8})$/i.exec(input.trim())
+  if (!match) return null
+  let hex = match[1]
+  if (hex.length === 3 || hex.length === 4) {
+    hex = hex
+      .split('')
+      .map((ch) => ch + ch)
+      .join('')
+  }
+  if (hex.length !== 6 && hex.length !== 8) return null
+  const r = parseInt(hex.slice(0, 2), 16) / 255
+  const g = parseInt(hex.slice(2, 4), 16) / 255
+  const b = parseInt(hex.slice(4, 6), 16) / 255
+  return srgbToOklch({ r, g, b })
+}
+
+// Named brand colors resolve to a vivid, mid-lightness OKLCH value so a request
+// for "orange" yields a genuinely chromatic primary even when the preset token
+// was achromatic (chroma 0). Hues mirror the runtime ACCENT_OKLCH palette.
+export const NAMED_COLORS = {
+  red: { l: 0.58, c: 0.22, h: 27 },
+  orange: { l: 0.62, c: 0.19, h: 55 },
+  amber: { l: 0.7, c: 0.17, h: 75 },
+  yellow: { l: 0.8, c: 0.16, h: 95 },
+  lime: { l: 0.72, c: 0.19, h: 130 },
+  green: { l: 0.6, c: 0.17, h: 155 },
+  teal: { l: 0.6, c: 0.13, h: 185 },
+  cyan: { l: 0.62, c: 0.13, h: 210 },
+  blue: { l: 0.58, c: 0.2, h: 232 },
+  indigo: { l: 0.55, c: 0.22, h: 264 },
+  violet: { l: 0.55, c: 0.22, h: 290 },
+  purple: { l: 0.55, c: 0.22, h: 310 },
+  pink: { l: 0.62, c: 0.2, h: 350 },
+  slate: { l: 0.45, c: 0.04, h: 240 },
+  gray: { l: 0.55, c: 0.02, h: 240 },
+  neutral: { l: 0.55, c: 0.0, h: 0 },
+  stone: { l: 0.5, c: 0.02, h: 60 },
+  zinc: { l: 0.5, c: 0.01, h: 240 },
+}
+
+// Parse any accepted color input into an OKLCH object, or null when unsupported.
+export function parseColor(input) {
+  if (typeof input !== 'string') return null
+  const value = input.trim()
+  if (value.startsWith('#') || value.startsWith('#')) return parseHex(value)
+  if (/^oklch\(/i.test(value)) return parseOklch(value)
+  const named = NAMED_COLORS[value.toLowerCase()]
+  if (named) return { ...named }
+  return null
+}
+
+export function isNamedColor(input) {
+  return typeof input === 'string' && Object.prototype.hasOwnProperty.call(NAMED_COLORS, input.trim().toLowerCase())
+}
+
+export const NAMED_COLOR_NAMES = Object.keys(NAMED_COLORS)

package/scripts/theme/css-theme.mjs

@@ -0,0 +1,233 @@
+// Bounded CSS theme extraction and merge.
+//
+// The storefront's visual tokens live in `:root` (light) and `.dark` blocks in
+// app/globals.css. This module reads those declarations and writes new values
+// back *in place*, preserving every unrelated byte — the Tailwind imports, the
+// `@theme inline` bridge, comments, and any token the CLI does not manage. It
+// never rewrites the whole stylesheet and never flattens `var()` aliases.
+
+// Scan `css` from the `{` at/after `from` to its matching `}`, ignoring braces
+// inside strings and comments. Returns the index just past the closing brace.
+function matchBrace(css, from) {
+  let depth = 0
+  let quote = null
+  for (let i = from; i < css.length; i++) {
+    const ch = css[i]
+    if (quote) {
+      if (ch === '\\') i++
+      else if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2)
+      i = end === -1 ? css.length : end + 1
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      continue
+    }
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) return i + 1
+    }
+  }
+  return -1
+}
+
+// Find the first top-level block whose selector is exactly `selector`. A block is
+// `selector { ... }`; we require the selector to be immediately followed (after
+// whitespace) by `{` so `.dark-something` never matches `.dark`.
+export function findBlock(css, selector) {
+  const re = new RegExp(`(^|[}\\s;])${selector.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\{`, 'g')
+  let match
+  while ((match = re.exec(css)) !== null) {
+    const braceIdx = css.indexOf('{', match.index)
+    const end = matchBrace(css, braceIdx)
+    if (end === -1) continue
+    const bodyStart = braceIdx + 1
+    return { start: match.index + (match[1] ? match[1].length : 0), bodyStart, bodyEnd: end - 1, end }
+  }
+  return null
+}
+
+// Split a block body into `--name: value` declarations, tracking their exact
+// offsets so callers can splice a single value without disturbing the rest.
+export function parseDeclarations(body, baseOffset = 0) {
+  const decls = []
+  let i = 0
+  while (i < body.length) {
+    const semi = indexOfTopLevel(body, ';', i)
+    const chunkEnd = semi === -1 ? body.length : semi
+    const chunk = body.slice(i, chunkEnd)
+    const colon = chunk.indexOf(':')
+    if (colon !== -1) {
+      const name = chunk.slice(0, colon).trim()
+      if (name.startsWith('--')) {
+        const valueStartInChunk = chunk.indexOf(':', colon) + 1
+        const rawValue = chunk.slice(valueStartInChunk)
+        const leading = rawValue.length - rawValue.trimStart().length
+        const trailing = rawValue.length - rawValue.trimEnd().length
+        const valueStart = i + valueStartInChunk + leading
+        const valueEnd = chunkEnd - trailing
+        decls.push({ name, value: body.slice(valueStart, valueEnd), valueStart: baseOffset + valueStart, valueEnd: baseOffset + valueEnd })
+      }
+    }
+    if (semi === -1) break
+    i = semi + 1
+  }
+  return decls
+}
+
+// Index of `ch` at paren/quote depth zero, or -1.
+function indexOfTopLevel(text, ch, from) {
+  let depth = 0
+  let quote = null
+  for (let i = from; i < text.length; i++) {
+    const c = text[i]
+    if (quote) {
+      if (c === '\\') i++
+      else if (c === quote) quote = null
+      continue
+    }
+    if (c === '"' || c === "'") quote = c
+    else if (c === '(') depth++
+    else if (c === ')') depth--
+    else if (c === ch && depth === 0) return i
+  }
+  return -1
+}
+
+// Read the theme declarations of a stylesheet into light/dark maps.
+export function readThemeCss(css) {
+  const read = (selector) => {
+    const block = findBlock(css, selector)
+    if (!block) return {}
+    const body = css.slice(block.bodyStart, block.bodyEnd)
+    const map = {}
+    for (const decl of parseDeclarations(body)) map[decl.name] = decl.value
+    return map
+  }
+  return { light: read(':root'), dark: read('.dark') }
+}
+
+// Apply a list of `{ scope, name, value }` edits, replacing existing
+// declarations in place and appending missing ones to the end of their block.
+// `scope` is 'light' (→ :root) or 'dark' (→ .dark). Returns the new CSS.
+export function applyDeclarations(css, edits) {
+  const groups = { light: [], dark: [] }
+  for (const edit of edits) {
+    if (!groups[edit.scope]) throw new Error(`Unknown theme scope: ${edit.scope}`)
+    groups[edit.scope].push(edit)
+  }
+  let out = css
+  for (const scope of ['light', 'dark']) {
+    if (groups[scope].length === 0) continue
+    out = applyBlockDeclarations(out, scope === 'light' ? ':root' : '.dark', groups[scope])
+  }
+  return out
+}
+
+// Apply `{ name, value }` edits to any block by selector, replacing existing
+// declarations in place and appending missing ones before the closing brace.
+// When the block does not exist it is created at the end of the file. Used for
+// the `@theme inline` font mapping, which is not a `:root` token block.
+export function applyBlockDeclarations(css, selector, edits) {
+  let block = findBlock(css, selector)
+  if (!block) {
+    // No block yet: create one at the end of the file, preserving everything.
+    const body = edits.map((e) => `  ${e.name}: ${e.value};`).join('\n')
+    const prefix = css.replace(/\s*$/, '')
+    return `${prefix}\n\n${selector} {\n${body}\n}\n`
+  }
+  const body = css.slice(block.bodyStart, block.bodyEnd)
+  const decls = parseDeclarations(body, block.bodyStart)
+  const byName = new Map(decls.map((d) => [d.name, d]))
+  // Collapse multiple edits to the same declaration to the last one, so
+  // precedence is "later wins" and each name is spliced exactly once.
+  const collapsed = []
+  const indexByName = new Map()
+  for (const edit of edits) {
+    if (indexByName.has(edit.name)) collapsed[indexByName.get(edit.name)] = edit
+    else {
+      indexByName.set(edit.name, collapsed.length)
+      collapsed.push(edit)
+    }
+  }
+  const inserts = []
+  // Apply from the end so earlier offsets stay valid as we splice.
+  const replacements = []
+  for (const edit of collapsed) {
+    const existing = byName.get(edit.name)
+    if (existing) replacements.push({ start: existing.valueStart, end: existing.valueEnd, value: edit.value })
+    else inserts.push(edit)
+  }
+  replacements.sort((a, b) => b.start - a.start)
+  let next = css
+  for (const rep of replacements) next = next.slice(0, rep.start) + rep.value + next.slice(rep.end)
+  if (inserts.length > 0) {
+    // Re-locate after replacements, then insert before the block's closing brace.
+    block = findBlock(next, selector)
+    const insertText = '\n' + inserts.map((e) => `  ${e.name}: ${e.value};`).join('\n')
+    next = next.slice(0, block.bodyEnd) + insertText + next.slice(block.bodyEnd)
+  }
+  return next
+}
+
+// Fill only the named tokens that are absent from each scope, leaving any value
+// a developer already set untouched. `defaults` is `{ light, dark }`.
+export function fillMissingTokens(css, tokens, defaults) {
+  const current = readThemeCss(css)
+  const edits = []
+  for (const scope of ['light', 'dark']) {
+    for (const token of tokens) {
+      const name = `--${token}`
+      if (current[scope][name] === undefined && defaults[scope][token] !== undefined) {
+        edits.push({ scope, name, value: defaults[scope][token] })
+      }
+    }
+  }
+  return applyDeclarations(css, edits)
+}
+
+// Collect `var(--x)` references in a declaration value.
+export function varReferences(value) {
+  const refs = []
+  const re = /var\(\s*(--[\w-]+)/g
+  let match
+  while ((match = re.exec(value)) !== null) refs.push(match[1])
+  return refs
+}
+
+// Detect references to undefined theme variables and reference cycles among the
+// declarations of a stylesheet. Returns `{ undefined: [...], cycles: [[...]] }`.
+export function validateVarReferences(css) {
+  const { light, dark } = readThemeCss(css)
+  const defined = new Set([...Object.keys(light), ...Object.keys(dark)])
+  const undefinedRefs = new Set()
+  const graph = new Map()
+  for (const scope of [light, dark]) {
+    for (const [name, value] of Object.entries(scope)) {
+      const refs = varReferences(value)
+      graph.set(name, refs)
+      for (const ref of refs) if (!defined.has(ref)) undefinedRefs.add(ref)
+    }
+  }
+  const cycles = []
+  const visiting = new Set()
+  const visited = new Set()
+  const walk = (node, path) => {
+    if (visiting.has(node)) {
+      cycles.push([...path.slice(path.indexOf(node)), node])
+      return
+    }
+    if (visited.has(node)) return
+    visiting.add(node)
+    for (const next of graph.get(node) ?? []) if (graph.has(next)) walk(next, [...path, node])
+    visiting.delete(node)
+    visited.add(node)
+  }
+  for (const node of graph.keys()) walk(node, [])
+  return { undefined: [...undefinedRefs], cycles }
+}

package/scripts/theme/fonts.mjs

@@ -0,0 +1,123 @@
+// Font wiring for the bounded external layout (task 3.3).
+//
+// A font selection is either a hosted Google family (`google:<Family>`, loaded
+// with `next/font/google`) or a CSS system stack (`system:<stack>`, no load).
+// Hosted fonts get a real `next/font` import + variable + `<html>` class so the
+// glyphs actually load; a bare family name is never treated as loaded. Only the
+// selected slots are touched, so an unselected local font wiring is preserved.
+
+function slug(family) {
+  return family
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function camel(family) {
+  return family
+    .trim()
+    .replace(/[^A-Za-z0-9]+(.)/g, (_, c) => c.toUpperCase())
+    .replace(/^./, (c) => c.toLowerCase())
+}
+
+// The identifier `next/font/google` exports for a family: each word capitalized
+// and joined with `_` (`Open Sans` -> `Open_Sans`, `inter` -> `Inter`). A family
+// stored as a lowercase slug (`inter`) still yields the correct export name.
+function importName(family) {
+  return family
+    .trim()
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('_')
+}
+
+const FONT_IMPORT_RE = /^import\s*\{([^}]*)\}\s*from\s*'next\/font\/google'\s*$/m
+
+/**
+ * Apply hosted font selections to app/layout.tsx. `fonts` is
+ * `{ sans?, mono?, serif? }` where each value is `{ kind: 'google'|'system',
+ * value }` or null. Returns `{ content, loaderVars, changed }`; `loaderVars`
+ * maps slot → the CSS variable next/font will inject (`--font-<slug>-<slot>`),
+ * so the stylesheet can point the Tailwind token at it.
+ */
+export function applyLayoutFonts(content, fonts = {}) {
+  const loaderVars = {}
+  let next = content
+  let changed = false
+
+  for (const slot of ['sans', 'mono', 'serif']) {
+    const selection = fonts[slot]
+    if (!selection || selection.kind !== 'google') continue
+    const family = selection.value
+    const varName = `--font-${slug(family)}-${slot}`
+    const binding = camel(family)
+    const exported = importName(family)
+    loaderVars[slot] = varName
+
+    // 1. Ensure the named import from next/font/google.
+    const existingImport = next.match(FONT_IMPORT_RE)
+    if (existingImport) {
+      const names = existingImport[1]
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+      if (!names.includes(exported)) {
+        names.push(exported)
+        next = next.replace(FONT_IMPORT_RE, `import { ${names.join(', ')} } from 'next/font/google'`)
+      }
+    } else {
+      const anchor = next.match(/^import[^\n]*$/m)
+      const importLine = `import { ${exported} } from 'next/font/google'`
+      next = anchor ? next.replace(anchor[0], `${anchor[0]}\n${importLine}`) : `${importLine}\n${next}`
+    }
+
+    // 2. Ensure the loader const.
+    const constRe = new RegExp(`const\\s+${binding}\\s*=\\s*${exported}\\(`)
+    if (!constRe.test(next)) {
+      const loader = `const ${binding} = ${exported}({ variable: '${varName}', subsets: ['latin'] })`
+      const lines = next.split('\n')
+      let lastImport = -1
+      for (let i = 0; i < lines.length; i++) if (lines[i].trimStart().startsWith('import ')) lastImport = i
+      if (lastImport >= 0) lines.splice(lastImport + 1, 0, '', loader)
+      else lines.unshift(loader, '')
+      next = lines.join('\n')
+    }
+
+    // 3. Ensure the variable is on the <html> className.
+    const htmlMatch = next.match(/<html\b([^>]*)>/)
+    if (htmlMatch) {
+      const attrs = htmlMatch[1]
+      if (!attrs.includes(`${binding}.variable`)) {
+        const classMatch = attrs.match(/className=\{([^}]*)\}/)
+        let newAttrs
+        if (classMatch) {
+          newAttrs = attrs.replace(classMatch[0], `className={[${classMatch[1]}, ${binding}.variable].join(' ')}`)
+        } else {
+          newAttrs = `${attrs} className={${binding}.variable}`
+        }
+        next = next.replace(htmlMatch[0], `<html${newAttrs}>`)
+      }
+    }
+  }
+
+  changed = next !== content
+  return { content: next, loaderVars, changed }
+}
+
+/**
+ * The stylesheet declarations a font selection implies. Hosted fonts map the
+ * Tailwind token to the variable next/font injects; system stacks are written
+ * directly. Returns a map of `--font-<slot>` → value.
+ */
+export function fontCssVars(fonts = {}, loaderVars = {}) {
+  const out = {}
+  for (const slot of ['sans', 'mono', 'serif']) {
+    const selection = fonts[slot]
+    if (!selection) continue
+    if (selection.kind === 'google' && loaderVars[slot]) out[`--font-${slot}`] = `var(${loaderVars[slot]})`
+    else if (selection.kind === 'system') out[`--font-${slot}`] = selection.value
+  }
+  return out
+}

package/scripts/theme/import-export.mjs

@@ -0,0 +1,125 @@
+// Portable theme import/export (tasks 4.2, 4.3).
+//
+// External theme sources are normalized through one data-only boundary:
+//   - a shadcn `registry:theme` JSON (`{ cssVars: { theme, light, dark } }`)
+//   - a local CSS export (a `:root` / `.dark` snippet from a generator)
+//   - a versioned storefront export written by `theme --export`
+// The normalized result is always `{ tokens: { light, dark }, fonts? }`, never a
+// second project config and never executable payloads.
+
+import { readThemeCss } from './css-theme.mjs'
+import { THEME_COLOR_TOKENS, FONT_VARS } from './tokens.mjs'
+
+export const EXPORT_FORMAT = 'storefront-theme'
+export const EXPORT_VERSION = 1
+
+function fail(code, message, extra = {}) {
+  return { ok: false, diagnostics: [{ code, severity: 'error', message, ...extra }] }
+}
+
+const THEME_VAR = /^--(?:[a-z0-9-]+)$/
+
+// Accept only theme-token and font declarations; drop anything else (component
+// files, scripts, arbitrary payloads) with a diagnostic rather than applying it.
+function filterDeclarations(raw) {
+  const kept = {}
+  const dropped = []
+  for (const [name, value] of Object.entries(raw ?? {})) {
+    if (typeof value !== 'string') {
+      dropped.push(name)
+      continue
+    }
+    const key = name.replace(/^--/, '')
+    if (THEME_COLOR_TOKENS.includes(key) || FONT_VARS.includes(name)) kept[name] = value
+    else dropped.push(name)
+  }
+  return { kept, dropped }
+}
+
+// A shadcn `registry:theme` item: cssVars.theme (shared) + cssVars.light/.dark.
+export function parseRegistryTheme(item) {
+  if (!item || typeof item !== 'object' || typeof item.cssVars !== 'object' || item.cssVars === null) {
+    return fail('E_IMPORT_SHAPE', 'registry:theme JSON must have a `cssVars` object')
+  }
+  const { theme = {}, light = {}, dark = {} } = item.cssVars
+  const dropped = []
+  const collect = (scope, raw) => {
+    const { kept, dropped: d } = filterDeclarations(raw)
+    dropped.push(...d)
+    return kept
+  }
+  const shared = collect('theme', theme)
+  const merged = { light: { ...shared, ...collect('light', light) }, dark: { ...shared, ...collect('dark', dark) } }
+  if (dropped.length) {
+    // Non-theme declarations are ignored, not an error: the theme tokens still apply.
+  }
+  return { ok: true, tokens: merged, fonts: {}, dropped }
+}
+
+// A local CSS export: a plain stylesheet snippet with `:root` / `.dark` blocks.
+export function parseCssExport(css) {
+  if (typeof css !== 'string' || !css.trim()) return fail('E_IMPORT_SHAPE', 'CSS theme export is empty')
+  const tokens = readThemeCss(css)
+  if (!Object.keys(tokens.light).length && !Object.keys(tokens.dark).length) {
+    return fail('E_IMPORT_SHAPE', 'CSS theme export has no `:root` or `.dark` token block')
+  }
+  return { ok: true, tokens, fonts: {} }
+}
+
+// Versioned storefront export written by `theme --export`.
+export function parseThemeExport(json) {
+  let parsed
+  try {
+    parsed = typeof json === 'string' ? JSON.parse(json) : json
+  } catch (error) {
+    return fail('E_IMPORT_JSON', `theme export is not valid JSON: ${error.message}`)
+  }
+  if (!parsed || typeof parsed !== 'object') return fail('E_IMPORT_SHAPE', 'theme export must be an object')
+  if (parsed.format !== EXPORT_FORMAT) {
+    return fail('E_IMPORT_FORMAT', `expected format "${EXPORT_FORMAT}" (got "${parsed.format}")`)
+  }
+  if (parsed.version !== EXPORT_VERSION) {
+    return fail('E_IMPORT_VERSION', `unsupported theme export version ${parsed.version} (supported: ${EXPORT_VERSION})`)
+  }
+  const tokens = parsed.tokens ?? {}
+  if (typeof tokens.light !== 'object' || typeof tokens.dark !== 'object') {
+    return fail('E_IMPORT_SHAPE', 'theme export must carry `tokens.light` and `tokens.dark`')
+  }
+  return { ok: true, tokens: { light: tokens.light, dark: tokens.dark }, fonts: parsed.fonts ?? {}, mode: parsed.mode ?? null }
+}
+
+// Build a portable, versioned export from the resolved palette. Declarative
+// font intent only (kind + value); no machine-specific module paths, secrets or
+// executable code.
+export function buildThemeExport({ tokens, mode, fonts = {} }) {
+  const fontSelections = {}
+  for (const slot of ['sans', 'mono', 'serif']) {
+    if (fonts[slot]) fontSelections[slot] = { kind: fonts[slot].kind, value: fonts[slot].value }
+  }
+  return {
+    format: EXPORT_FORMAT,
+    version: EXPORT_VERSION,
+    mode: mode ?? null,
+    tokens: { light: tokens.light ?? {}, dark: tokens.dark ?? {} },
+    fonts: fontSelections,
+  }
+}
+
+// Detect the concrete input type of an import source so a URL/format mismatch
+// produces an actionable diagnostic instead of a confusing parse failure.
+export function classifyImportSource(raw) {
+  const text = String(raw).trim()
+  if (/^https?:\/\//.test(text)) {
+    if (/\/r\/|registry|\.json(\?|$)/.test(text) && !/ui\.shadcn\.com\/create/.test(text)) {
+      return 'registry-url'
+    }
+    return 'preset-url'
+  }
+  if (text.startsWith('{')) return 'json'
+  if (text.includes('{')) return 'css'
+  // A path is classified by extension so a stylesheet that has no block on the
+  // command line (the common case: `--import ./brand.css`) still resolves.
+  if (/\.json(\?|$)/i.test(text)) return 'json'
+  if (/\.css(\?|$)/i.test(text)) return 'css'
+  return 'unknown'
+}