sh-ui-cli 0.34.0 → 0.39.0

package/data/changelog/versions.json

@@ -2,6 +2,42 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.39.0",
+      "date": "2026-04-29",
+      "title": "프리셋 정체성 강화 — slate / rose / violet 이 typography·controls·borders 도 차별화",
+      "type": "minor",
+      "highlights": [
+        "0.38.0 까지 5 프리셋이 색·radius 만 차별화 → 이제 typography·controls·borders 까지 프리셋 별 인상이 다름. neutral / emerald 는 디폴트 baseline (변화 없음), 나머지 셋은 정체성 부여",
+        "**slate** (정보 밀도) — text-base 14px (xs 11/sm 12/lg 16/xl 18/2xl 21/3xl 26/4xl 32), control-md 36px (sm 28/lg 44). 대시보드/관리자 인상",
+        "**rose** (친근·여유) — control-md 44px (sm 36/lg 52). 큼직한 터치 타겟 + 0.75rem 라운드 → 소비자 앱 인상",
+        "**violet** (모던·또렷) — control-md 42px (sm 34/lg 50), border-width-strong 3px (디폴트 2px). 약간 두꺼운 강조 보더로 창의·디자인 도구 인상",
+        "getThemePreset 시그니처 — 이전 `{light, dark, radius}` 만 → 이제 label 빼고 모든 카테고리 forward. CLI inject 가 자동으로 마커 섹션 교체",
+        "api.d.ts ThemePreset 인터페이스에 옵셔널 카테고리 6종 추가 (typography/controls/borders/spacing/weights/durations) — apps/docs 등 외부 사용자가 타입 안전",
+        "테스트 111개 (전 104 → +7). end-to-end 검증 — `--theme rose` 가 control-md 40 → 44 로 덮어쓰는지, `--theme slate` 가 text-base 16 → 14 로, `--theme violet` 이 border-width-strong 2 → 3 으로",
+        "참고: 기존 사용자가 0.38.0 까지 `--theme rose` 로 만든 프로젝트는 영향 없음 (이미 생성된 tokens.css 는 그대로). 새로 `--theme rose` 하면 0.39.0 정체성 그대로 들어감"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.39.0"
+    },
+    {
+      "version": "0.38.0",
+      "date": "2026-04-29",
+      "title": "테마 시스템 풀스택 — 5 프리셋 + 풀 토큰 편집기 + 스캐폴드 threading + CSS↔Flutter 변환기",
+      "type": "minor",
+      "highlights": [
+        "**프리셋 5종 (CLI + 플레이그라운드)** — neutral · slate · rose · emerald · violet. `sh-ui create --theme rose` 처럼 짧게 받거나 playground 에서 만든 base64 그대로. 플레이그라운드 토큰 편집기 위쪽 '프리셋' 행 클릭 한 번으로 light/dark/radius 동시 적용. sh-ui-cli/api 가 단일 소스",
+        "**쉬운 / 고급 토글** — 쉬운 모드는 베이스 톤 4(neutral/slate/warm/cool) + 포인트 컬러 1개 픽커(primary-foreground/primary-hover 자동 파생). 고급 모드는 8 카테고리 collapsible 섹션 — 색(15) · 크기 · 테두리 · 그림자 · 타이포 · 여백 · 폰트굵기 · 모션. 모든 슬라이더는 sh-ui Slider 사용",
+        "**그라데이션 빌더 + 슬롯 3개** (primary/surface/overlay) — 각도 슬라이더 + 2 컬러스톱 + 위치 슬라이더 + 라이브 프리뷰. CSS 변수 `--gradient-*` 로 캔버스 흘러감",
+        "**스캐폴드 threading 풀스택** — 색 15 + radius + 9 옵셔널 카테고리 (spacing 11 / typography 8 / weights 4 / controls 3 / borders 2 / durations 3 / shadows 4 / eases 2 / gradients 3). theme JSON 에 키가 있으면 tokens.css / sh_ui_tokens.dart 의 마커 섹션 교체, 없으면 템플릿 디폴트 유지. 디폴트와 다른 카테고리만 base64 에 포함돼 페이로드 최소화",
+        "**CSS↔Flutter 변환기** — shadow `0 1px 2px rgba(0,0,0,0.08)` → `BoxShadow(offset, blurRadius, spreadRadius, color: Color(0x14000000))` (alpha = 0.08 × 255). ease `cubic-bezier(0.4,0,0.2,1)` → `Cubic(0.4,0,0.2,1)` (named easing 도 정확한 4-인자로). gradient `linear-gradient(135deg, ...)` → `LinearGradient(begin: Alignment(-0.707,-0.707), end: Alignment(0.707,0.707), colors, stops)`. CSS deg → Flutter Alignment (0deg=topCenter, 시계방향)",
+        "**확장 색 직접 편집** — background-inverse / foreground-inverse / foreground-subtle 3개를 사용자가 직접 잡음. 기존 Dart 자동 inverse 거울 / 고정 foregroundSubtle 디폴트 폐기. 5 프리셋 light/dark 모두 15키 풀세트",
+        "**Flutter 템플릿** — ShUiGradientTokens 클래스 신설 + ShUiTheme 에 gradient 필드 통합. tokens.css / sh_ui_tokens.dart 에 카테고리별 마커 9쌍 (theme-space/text/weight/shadow/duration/ease/control/border-width/gradient)",
+        "**DatePicker 회귀 픽스 2개** — (1) container prop 누락 → 추가 (Select·Combobox·Popover 와 동일 패턴). 다크 모드를 page subtree 에만 입힌 환경에서 캘린더 popover 가 토큰 스코프 벗어나 흰 배경으로 뜨던 문제 해결. (2) 선택일 색을 --foreground 에서 --primary / --primary-foreground 로 전환 — rose/emerald 같은 primary 변경 프리셋이 캘린더에도 일관되게 반영. **호환성 주의**: primary 를 안 바꾸고 쓰던 사용자는 선택일 색이 검정 → 자기 primary 색으로 변경됨",
+        "**MCP** sh_ui_create_project 의 theme 파라미터가 프리셋 이름 수용 — IDE 에이전트가 `theme: \"slate\"` 한 줄로 호출. 짧은 오타는 base64 디코드 에러 대신 '알 수 없는 테마 프리셋: 지원 목록 …' 친절 안내",
+        "**테스트 104** (전 68 → +36). 옵셔널 카테고리 검증, 빌더 출력 형식, 파서 (rgba alpha / hex 8자리 / spread / multi-shadow / named ease / Alignment 각도 0·45·90·135·180), 잘못된 형식 throw, end-to-end Next + Flutter 스캐폴드 주입. localStorage 마이그레이션 (v0.34 까지 저장된 데이터는 새 키 디폴트 보강)"
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.38.0"
+    },
     {
       "version": "0.34.0",
       "date": "2026-04-29",

package/data/registry/react/components/date-picker/index.tsx

@@ -329,6 +329,11 @@ export interface DatePickerProps {
    * @default true
    */
   closeOnSelect?: boolean;
+  /**
+   * Portal이 마운트될 DOM 노드. 토큰 스코프(다크 모드 등) 안에 popover를 띄우려면 해당 컨테이너 ref 전달.
+   * @default document.body
+   */
+  container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
   /**
    * compound 모드. 미지정 시 기본 레이아웃(Trigger + Content + Calendar)이 자동 렌더된다.
    * 직접 조립하려면 `DatePickerTrigger`/`DatePickerContent`/`DatePickerCalendar`/`DatePickerFooter`를 자식으로 넘긴다.
@@ -353,6 +358,7 @@ export function DatePicker({
   "aria-invalid": ariaInvalid,
   className,
   closeOnSelect = true,
+  container,
   children,
 }: DatePickerProps) {
   const isControlled = value !== undefined;
@@ -417,7 +423,7 @@ export function DatePicker({
         {children ?? (
           <>
             <DatePickerTrigger className={className} />
-            <DatePickerContent>
+            <DatePickerContent container={container}>
               <DatePickerCalendar />
             </DatePickerContent>
           </>
@@ -525,19 +531,24 @@ export interface DatePickerContentProps
    * @default "start"
    */
   align?: React.ComponentPropsWithoutRef<typeof BasePopover.Positioner>["align"];
+  /**
+   * Portal이 마운트될 DOM 노드. 토큰 스코프(다크 모드 등) 안에 popover를 띄우려면 해당 컨테이너 ref 전달.
+   * @default document.body
+   */
+  container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
 }
 
 /** 캘린더 popover 본문. portal로 마운트되며 `disabled`/`readOnly`이면 렌더되지 않는다. */
 export const DatePickerContent = React.forwardRef<HTMLDivElement, DatePickerContentProps>(
   function DatePickerContent(
-    { className, children, sideOffset = 4, side = "bottom", align = "start", ...props },
+    { className, children, sideOffset = 4, side = "bottom", align = "start", container, ...props },
     ref,
   ) {
     const ctx = useDatePickerContext("DatePickerContent");
     if (ctx.disabled || ctx.readOnly) return null;
 
     return (
-      <BasePopover.Portal>
+      <BasePopover.Portal container={container}>
         <BasePopover.Positioner
           className="sh-ui-date-picker__positioner"
           sideOffset={sideOffset}
@@ -639,6 +650,11 @@ export interface DateRangePickerProps {
   /** invalid 상태. */
   "aria-invalid"?: boolean | "true";
   className?: string;
+  /**
+   * Portal이 마운트될 DOM 노드. 토큰 스코프(다크 모드 등) 안에 popover를 띄우려면 해당 컨테이너 ref 전달.
+   * @default document.body
+   */
+  container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>["container"];
 }
 
 /**
@@ -659,6 +675,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
       readOnly,
       "aria-invalid": ariaInvalid,
       className,
+      container,
     },
     ref,
   ) {
@@ -724,7 +741,7 @@ export const DateRangePicker = React.forwardRef<HTMLButtonElement, DateRangePick
         </BasePopover.Trigger>
 
         {!disabled && !readOnly && (
-          <BasePopover.Portal>
+          <BasePopover.Portal container={container}>
             <BasePopover.Positioner
               className="sh-ui-date-picker__positioner"
               sideOffset={4}

package/data/registry/react/components/date-picker/styles.css

@@ -207,37 +207,37 @@
 }
 
 .sh-ui-calendar__day--selected {
-  background: var(--foreground);
-  color: var(--background);
+  background: var(--primary);
+  color: var(--primary-foreground);
   font-weight: var(--weight-semibold);
 }
 
 .sh-ui-calendar__day--selected:hover:not(:disabled) {
-  background: var(--foreground);
-  opacity: 0.9;
+  background: var(--primary-hover);
+  color: var(--primary-foreground);
 }
 
 /* ── Range ── */
 
 .sh-ui-calendar__day--in-range {
-  background: color-mix(in srgb, var(--foreground) 10%, transparent);
+  background: color-mix(in srgb, var(--primary) 12%, transparent);
   border-radius: 0;
 }
 
 .sh-ui-calendar__day--in-range:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--foreground) 18%, transparent);
+  background: color-mix(in srgb, var(--primary) 22%, transparent);
 }
 
 .sh-ui-calendar__day--range-start {
-  background: var(--foreground);
-  color: var(--background);
+  background: var(--primary);
+  color: var(--primary-foreground);
   font-weight: var(--weight-semibold);
   border-radius: calc(var(--radius) - 2px) 0 0 calc(var(--radius) - 2px);
 }
 
 .sh-ui-calendar__day--range-end {
-  background: var(--foreground);
-  color: var(--background);
+  background: var(--primary);
+  color: var(--primary-foreground);
   font-weight: var(--weight-semibold);
   border-radius: 0 calc(var(--radius) - 2px) calc(var(--radius) - 2px) 0;
 }
@@ -248,8 +248,8 @@
 
 .sh-ui-calendar__day--range-start:hover:not(:disabled),
 .sh-ui-calendar__day--range-end:hover:not(:disabled) {
-  background: var(--foreground);
-  opacity: 0.9;
+  background: var(--primary-hover);
+  color: var(--primary-foreground);
 }
 
 /* ── Hint (range picker) ── */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.34.0",
+  "version": "0.39.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/api.d.ts

@@ -40,3 +40,34 @@ export type PluginManifest = {
 };
 
 export const allPlugins: readonly PluginManifest[];
+
+/* ─────── 테마 프리셋 ─────── */
+
+export type ThemePresetName = 'neutral' | 'slate' | 'rose' | 'emerald' | 'violet';
+
+/** decode.js 의 TOKEN_KEYS — light/dark 양쪽이 가져야 하는 키 12개. */
+export type ThemeTokenKey =
+  | 'background' | 'background-subtle' | 'background-muted'
+  | 'foreground' | 'foreground-muted'
+  | 'border' | 'border-strong'
+  | 'primary' | 'primary-foreground' | 'primary-hover'
+  | 'danger' | 'danger-foreground';
+
+export interface ThemePreset {
+  /** UI 에 표시할 사람이 읽는 라벨. */
+  label: string;
+  light: Record<ThemeTokenKey, string>;
+  dark: Record<ThemeTokenKey, string>;
+  /** rem 단위 (0~1.5). */
+  radius: number;
+  /** v0.39.0+ — 프리셋 별 정체성 차별화 (옵셔널). decode.js SCALAR_CATEGORIES 와 동일 키. */
+  typography?: Record<string, number>;
+  controls?: Record<string, number>;
+  borders?: Record<string, number>;
+  spacing?: Record<string, number>;
+  weights?: Record<string, number>;
+  durations?: Record<string, number>;
+}
+
+export const THEME_PRESETS: Record<ThemePresetName, ThemePreset>;
+export const THEME_PRESET_NAMES: readonly ThemePresetName[];

package/src/api.js

@@ -19,3 +19,4 @@ export {
 } from './constants.js';
 
 export { allPlugins } from './create/plugins/index.js';
+export { THEME_PRESETS, THEME_PRESET_NAMES } from './create/theme/presets.js';

package/src/create/generator.js

@@ -4,13 +4,32 @@ import fs from 'fs-extra';
 import os from 'node:os';
 import path from 'node:path';
 import { getPluginChoices, getPluginsByNames } from './plugins/index.js';
-import { decodeTheme } from './theme/decode.js';
+import { resolveTheme } from './theme/decode.js';
+import { THEME_PRESETS, getThemePreset } from './theme/presets.js';
 import {
   replaceSection,
   buildCssColorsBlock,
   buildCssRadiusBlock,
+  buildCssSpacingBlock,
+  buildCssTypographyBlock,
+  buildCssWeightsBlock,
+  buildCssControlsBlock,
+  buildCssBordersBlock,
+  buildCssDurationsBlock,
+  buildCssShadowsBlock,
+  buildCssEasesBlock,
+  buildCssGradientsBlock,
   buildDartColorsBlock,
   buildDartRadiusBlock,
+  buildDartSpacingBlock,
+  buildDartTypographyBlock,
+  buildDartWeightsBlock,
+  buildDartControlsBlock,
+  buildDartBordersBlock,
+  buildDartDurationsBlock,
+  buildDartShadowsBlock,
+  buildDartEasesBlock,
+  buildDartGradientsBlock,
 } from './theme/inject.js';
 import { getTemplatesRoot } from '../paths.mjs';
 
@@ -52,7 +71,25 @@ export async function createProject(options = {}) {
     ],
   });
 
-  const theme = options.theme ? decodeTheme(options.theme) : null;
+  let theme = null;
+  if (options.theme) {
+    theme = resolveTheme(options.theme);
+  } else if (process.stdin.isTTY && !options.yes) {
+    // --yes 는 "선택 옵션은 기본값으로" 의미. 테마는 옵션이므로 prompt 우회.
+    const NONE = '__none__';
+    const choice = await select({
+      message: '테마:',
+      default: NONE,
+      choices: [
+        { name: '기본 (테마 없음 — sh-ui 기본 토큰 그대로)', value: NONE },
+        ...Object.entries(THEME_PRESETS).map(([name, preset]) => ({
+          name: preset.label,
+          value: name,
+        })),
+      ],
+    });
+    if (choice !== NONE) theme = getThemePreset(choice);
+  }
 
   // dry-run 은 tmpdir 에 그대로 생성한 뒤 파일 목록 출력 + 정리.
   // 사용자 cwd 를 건드리지 않으면서 실제 generation 흐름을 그대로 검증한다.
@@ -601,6 +638,34 @@ async function applyTransforms(targetDir, plugins) {
 // ─── Theme 주입 ───
 
 /** 여러 후보 경로 중 존재하는 첫 tokens.css 에 theme 주입 */
+/**
+ * 옵셔널 카테고리 → CSS 마커 / 빌더 매핑.
+ * theme 에 카테고리 키가 있을 때만 해당 마커 섹션 교체.
+ */
+const OPTIONAL_CSS_INJECTORS = [
+  ['spacing',    'theme-space',        buildCssSpacingBlock],
+  ['typography', 'theme-text',         buildCssTypographyBlock],
+  ['weights',    'theme-weight',       buildCssWeightsBlock],
+  ['controls',   'theme-control',      buildCssControlsBlock],
+  ['borders',    'theme-border-width', buildCssBordersBlock],
+  ['durations',  'theme-duration',     buildCssDurationsBlock],
+  ['shadows',    'theme-shadow',       buildCssShadowsBlock],
+  ['eases',      'theme-ease',         buildCssEasesBlock],
+  ['gradients',  'theme-gradient',     buildCssGradientsBlock],
+];
+
+const OPTIONAL_DART_INJECTORS = [
+  ['spacing',    'theme-space',        buildDartSpacingBlock],
+  ['typography', 'theme-text',         buildDartTypographyBlock],
+  ['weights',    'theme-weight',       buildDartWeightsBlock],
+  ['controls',   'theme-control',      buildDartControlsBlock],
+  ['borders',    'theme-border-width', buildDartBordersBlock],
+  ['durations',  'theme-duration',     buildDartDurationsBlock],
+  ['shadows',    'theme-shadow',       buildDartShadowsBlock],
+  ['eases',      'theme-ease',         buildDartEasesBlock],
+  ['gradients',  'theme-gradient',     buildDartGradientsBlock],
+];
+
 async function injectCssTheme(projectDir, theme) {
   if (!theme) return;
   const candidates = [
@@ -613,6 +678,11 @@ async function injectCssTheme(projectDir, theme) {
       let css = await fs.readFile(abs, 'utf-8');
       css = replaceSection(css, 'theme-colors', '/*', '*/', buildCssColorsBlock(theme));
       css = replaceSection(css, 'theme-radius', '/*', '*/', buildCssRadiusBlock(theme));
+      for (const [key, marker, builder] of OPTIONAL_CSS_INJECTORS) {
+        if (theme[key]) {
+          css = replaceSection(css, marker, '/*', '*/', builder(theme[key]));
+        }
+      }
       await fs.writeFile(abs, css);
       return;
     }
@@ -629,5 +699,10 @@ async function injectDartTheme(projectDir, theme) {
   let dart = await fs.readFile(abs, 'utf-8');
   dart = replaceSection(dart, 'theme-colors', '//', '', buildDartColorsBlock(theme));
   dart = replaceSection(dart, 'theme-radius', '//', '', buildDartRadiusBlock(theme));
+  for (const [key, marker, builder] of OPTIONAL_DART_INJECTORS) {
+    if (theme[key]) {
+      dart = replaceSection(dart, marker, '//', '', builder(theme[key]));
+    }
+  }
   await fs.writeFile(abs, dart);
 }

package/src/create/index.mjs

@@ -4,9 +4,11 @@ import { parseArgs } from './cli-args.js';
 import { createProject, addApp, addComponent } from './generator.js';
 import { allPlugins } from './plugins/index.js';
 import { CREATE_PLATFORMS, CREATE_STRUCTURES } from '../constants.js';
+import { THEME_PRESET_NAMES } from './theme/presets.js';
 
 const PLUGIN_NAMES = allPlugins.map((p) => p.name);
 const PLUGINS_LIST = PLUGIN_NAMES.join(', ');
+const THEME_PRESETS_LIST = THEME_PRESET_NAMES.join('|');
 
 export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next.js / Flutter)
 
@@ -19,7 +21,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
   --platform <${CREATE_PLATFORMS.join('|')}>          타겟 플랫폼
   --structure <${CREATE_STRUCTURES.join('|')}>  Next.js 프로젝트 구조 (next 일 때)
   --plugins <a,b>                    플러그인 (${PLUGINS_LIST}). 미지정/"" → 없음
-  --theme <base64>                   테마 JSON (base64). 선택
+  --theme <preset|base64>            프리셋 이름(${THEME_PRESETS_LIST}) 또는 playground base64. 선택
   --yes                              디렉토리 덮어쓰기 + 모노레포 기본값 자동 채택
   --dry-run                          파일을 쓰지 않고 작성될 파일 목록만 출력
   -h, --help                         이 도움말
@@ -30,6 +32,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
 예 (비대화형 / 에이전트 / CI):
   sh-ui create my-app --platform next --structure standalone --yes
   sh-ui create my-app --platform next --structure monorepo --plugins ${PLUGIN_NAMES.slice(0, 3).join(',')} --yes
+  sh-ui create my-app --platform next --structure standalone --theme rose --yes
   sh-ui create my-app --platform flutter --yes
 
 비대화형 환경(TTY 없음)에서는 누락된 필수 인자가 있으면 prompt 대신 에러로 종료한다.

package/src/create/theme/decode.js

@@ -1,11 +1,81 @@
+import { getThemePreset, THEME_PRESET_NAMES } from './presets.js';
+
 const TOKEN_KEYS = [
-  'background', 'background-subtle', 'background-muted',
-  'foreground', 'foreground-muted',
+  'background', 'background-subtle', 'background-muted', 'background-inverse',
+  'foreground', 'foreground-muted', 'foreground-subtle', 'foreground-inverse',
   'border', 'border-strong',
   'primary', 'primary-foreground', 'primary-hover',
   'danger', 'danger-foreground',
 ];
 
+/**
+ * 옵셔널 카테고리 검증 — 모두 Record<string, number>.
+ * 카테고리 누락은 OK (스캐폴드 시 해당 블록은 디폴트 유지). 형식만 위배되면 에러.
+ *
+ * 각 카테고리의 expectedKeys 가 정확히 일치해야 함 — 나머지/누락 키 모두 거부.
+ */
+const SCALAR_CATEGORIES = {
+  spacing: ['0', '1', '2', '3', '4', '5', '6', '8', '10', '12', '16'],
+  typography: ['xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl'],
+  weights: ['regular', 'medium', 'semibold', 'bold'],
+  controls: ['sm', 'md', 'lg'],
+  borders: ['width', 'widthStrong'],
+  durations: ['fast', 'base', 'slow'],
+};
+
+/** Phase 3 — 문자열 카테고리. 형식 자체 검증은 inject 빌더에서 (CSS 그대로 통과 + Dart 변환 시 throw). */
+const STRING_CATEGORIES = {
+  shadows: ['sm', 'md', 'lg', 'xl'],
+  eases: ['standard', 'emphasized'],
+  gradients: ['primary', 'surface', 'overlay'],
+};
+
+const validateStringCategory = (name, expectedKeys, value) => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`theme 디코드 실패: ${name} 가 객체가 아님`);
+  }
+  for (const key of expectedKeys) {
+    if (!(key in value)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 누락`);
+    }
+    const v = value[key];
+    if (typeof v !== 'string' || v.length === 0) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 빈 문자열 또는 비-문자열 (받은 값: ${JSON.stringify(v)})`);
+    }
+    if (v.length > 512) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 너무 김 (>512자)`);
+    }
+  }
+  for (const key of Object.keys(value)) {
+    if (!expectedKeys.includes(key)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 는 알 수 없는 키`);
+    }
+  }
+};
+
+const validateScalarCategory = (name, expectedKeys, value) => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`theme 디코드 실패: ${name} 가 객체가 아님`);
+  }
+  for (const key of expectedKeys) {
+    if (!(key in value)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 누락`);
+    }
+    const v = value[key];
+    if (typeof v !== 'number' || Number.isNaN(v) || !Number.isFinite(v)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 유한 숫자가 아님 (받은 값: ${JSON.stringify(v)})`);
+    }
+    if (v < 0) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 가 음수 (받은 값: ${v})`);
+    }
+  }
+  for (const key of Object.keys(value)) {
+    if (!expectedKeys.includes(key)) {
+      throw new Error(`theme 디코드 실패: ${name}.${key} 는 알 수 없는 키`);
+    }
+  }
+};
+
 const HEX_REGEX = /^#[0-9A-Fa-f]{6}$/;
 const BASE64_REGEX = /^[A-Za-z0-9+/]*={0,2}$/;
 const MAX_THEME_BYTES = 10 * 1024; // 정상 테마 ~860 바이트. 10KB 면 10× 여유.
@@ -60,7 +130,40 @@ export const decodeTheme = (b64) => {
   if (parsed.radius < 0 || parsed.radius > 1.5) {
     throw new Error(`theme 디코드 실패: radius 가 허용 범위(0~1.5)를 벗어남 (${parsed.radius})`);
   }
+  // 옵셔널 카테고리 — 누락은 OK, 들어 있으면 형식 검증.
+  for (const [category, expectedKeys] of Object.entries(SCALAR_CATEGORIES)) {
+    if (category in parsed) {
+      validateScalarCategory(category, expectedKeys, parsed[category]);
+    }
+  }
+  for (const [category, expectedKeys] of Object.entries(STRING_CATEGORIES)) {
+    if (category in parsed) {
+      validateStringCategory(category, expectedKeys, parsed[category]);
+    }
+  }
   return parsed;
 };
 
-export { TOKEN_KEYS };
+/**
+ * --theme 입력 1개 슬롯에 프리셋 이름과 base64 둘 다 받기 위한 리졸버.
+ * 프리셋 이름이면 미리 정의된 ThemeConfig 를, 그 외엔 base64 로 간주해 decodeTheme 위임.
+ * THEME_PRESET_NAMES 와 base64 알파벳은 둘 다 [a-z]+ 와 충돌하지만 프리셋 사전 매칭이 우선이라
+ * 'rose' 같이 우연히 base64 로도 파싱 가능한 짧은 토큰은 프리셋으로 해석된다 (의도).
+ */
+export const resolveTheme = (input) => {
+  if (typeof input !== 'string') {
+    throw new Error(`theme 입력 실패: 문자열이 아님`);
+  }
+  const preset = getThemePreset(input);
+  if (preset) return preset;
+  // 정상 base64 테마는 200자 이상. 그보다 짧으면 프리셋 오타로 보고 친절한 에러를.
+  if (input.length < 50) {
+    throw new Error(
+      `알 수 없는 테마 프리셋: '${input}'. 지원: ${THEME_PRESET_NAMES.join(', ')} ` +
+      `(또는 playground 에서 생성한 base64).`
+    );
+  }
+  return decodeTheme(input);
+};
+
+export { TOKEN_KEYS, THEME_PRESET_NAMES };