sh-ui-cli 0.71.2 → 0.73.0

package/bin/sh-ui.mjs

@@ -29,6 +29,9 @@ const usage = `사용법:
                                    디렉토리 + 모든 import/path 패턴)
   sh-ui migrate-v065               v0.64.x → v0.65 자동 마이그레이션
                                    (--dry-run 기본, --apply 로 실제 적용)
+  sh-ui migrate bundled            cssStrategy=bundled 로 전환 (per-component
+                                   styles.css → 단일 sh-ui-components.css)
+                                   (--apply 로 실제 적용)
   sh-ui mcp                        MCP 서버(stdio) 시작 — IDE-내 AI용
   sh-ui mcp init --client <name>   IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
                                    (claude-code | cursor | claude-desktop)
@@ -224,6 +227,22 @@ try {
       await renameApp({ cwd: process.cwd(), oldName, newName, yes, dryRun, skipInstall });
       break;
     }
+    case "migrate": {
+      // sh-ui migrate bundled [--apply] [--bundle <path>]
+      const sub = rest[0];
+      const flags = rest.slice(1);
+      if (sub === "bundled") {
+        const apply = flags.includes("--apply");
+        const bIdx = flags.indexOf("--bundle");
+        const bundleArg = bIdx !== -1 ? flags[bIdx + 1] : null;
+        const { runMigrateBundled } = await import("../src/migrate-bundled.mjs");
+        await runMigrateBundled({ cwd: process.cwd(), apply, bundleArg });
+      } else {
+        console.error(`에러: 알 수 없는 migrate 서브명령 '${sub ?? ""}'. 'bundled' 만 지원.\n`);
+        process.exit(1);
+      }
+      break;
+    }
     case "migrate-v065": {
       const apply = rest.includes("--apply");
       const skipImportRewrite = rest.includes("--skip-import-rewrite");

package/data/changelog/versions.json

@@ -2,6 +2,34 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.73.0",
+      "date": "2026-05-10",
+      "title": "Flutter — theme extract + tokens diff/upgrade Dart 지원",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui theme extract` Flutter 지원** — `sh_ui_tokens.dart` 의 `static const light/dark` 블록에서 `Color(0xFFRRGGBB)` 를 추출해 sh-ui base64 로 인코딩. alpha 채널은 무시 (#RRGGBB 만 인코딩), `defaultRadius` 픽셀값을 16 으로 나눠 rem 변환.",
+        "**`sh-ui tokens diff` Flutter 지원** — Dart 의 `static const` 블록을 `<ClassName>.<staticName>` 키로 평탄화 후 field-level 비교. nested 함수 호출 (`Color(0x...)`, `Cubic(0.4, 0, 0.2, 1)`, `Duration(milliseconds: 120)`, `<BoxShadow>[...]`) 를 깊이 카운터로 안전하게 split — 간단 정규식 파서가 깨지지 않음.",
+        "**`sh-ui tokens upgrade --replace` Flutter 지원** — buildTokensDart 결과로 통째 덮어쓰기.",
+        "**`--apply` 는 Flutter 미지원** — Dart 클래스에 필드 추가는 (1) class field 선언, (2) constructor 파라미터, (3) 모든 static const 인스턴스화 3 군데를 동시에 수정해야 해서 incremental 적용이 위험. 친절 에러로 안내 + `--replace` 권장.",
+        "**dispatch 통합** — tokens-cmd / theme-extract 가 platform 으로 분기. React (CSS) 와 Flutter (Dart) 가 같은 명령 표면 공유."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.73.0"
+    },
+    {
+      "version": "0.72.0",
+      "date": "2026-05-10",
+      "title": "sh-ui migrate bundled — per-component → bundled 자동 전환 (Phase D 후속)",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui migrate bundled` 명령** — 기존 per-component 프로젝트를 bundled 로 한 번에 전환. paths.components 아래 모든 styles.css 를 bundle 의 마커 섹션으로 누적 + 원본 파일 삭제 + .tsx import 제거 + config 갱신.",
+        "**dry-run 기본** — 변경 매트릭스 (대상 컴포넌트 + 파일 목록) 출력 후 사용자 확인. `--apply` 로만 실제 변경.",
+        "**`--bundle <path>` 옵션** — bundle 파일 위치 명시. 미지정 시 paths.styles 또는 paths.tokens 디렉토리 + sh-ui-components.css 를 자동 사용.",
+        "**완료 후 안내** — globals.css 에 `@import './sh-ui-components.css';` 한 줄 추가하라는 메시지 (자동 편집 안 함 — 사용자 entry CSS 위치/스타일 다양해서).",
+        "**제약** — cssFramework: plain + React 만. tailwind/css-modules/vanilla-extract 면 친절 에러. 이미 bundled 면 noop."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.72.0"
+    },
     {
       "version": "0.71.2",
       "date": "2026-05-09",

package/package.json

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

package/src/migrate-bundled.mjs

@@ -0,0 +1,172 @@
+// `sh-ui migrate bundled` — 기존 per-component 프로젝트를 cssStrategy: bundled 로 전환.
+//
+// 동작:
+//   1) sh-ui.config.json 의 cssStrategy 가 미설정/per-component 인지 확인.
+//   2) 사용자에게 paths.cssBundle 위치 안내 (기본값 자동 결정 — paths.styles 또는
+//      paths.tokens 의 디렉토리 + `sh-ui-components.css`).
+//   3) paths.components 아래 모든 `<name>/styles.css` 를 읽어 bundle 에 섹션으로 누적.
+//   4) 각 컴포넌트 .tsx 의 `import "./styles.css";` 라인 제거.
+//   5) per-component styles.css 파일 삭제.
+//   6) sh-ui.config.json 에 `cssStrategy: "bundled"` + `paths.cssBundle` 저장.
+//
+// dry-run 기본 — 실제 변경은 --apply 로만. 실행 전 사용자에게 변경 매트릭스 안내.
+
+import { readFile, writeFile, readdir, rm, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, relative, dirname, join } from "node:path";
+import { upsertSection, stripStylesImport } from "./css-bundle.mjs";
+
+async function loadConfig(cwd) {
+  const configPath = resolve(cwd, "sh-ui.config.json");
+  if (!existsSync(configPath)) {
+    throw new Error(
+      "sh-ui.config.json 을 찾을 수 없습니다. 먼저 `sh-ui init` 또는 `sh-ui create`.",
+    );
+  }
+  return { configPath, config: JSON.parse(await readFile(configPath, "utf8")) };
+}
+
+/**
+ * paths.cssBundle 기본값 — 기존 paths.styles 또는 paths.tokens 의 부모 디렉토리에
+ * `sh-ui-components.css` 를 둔다.
+ */
+function defaultBundlePath(config) {
+  const stylesDir = config.paths?.styles
+    ?? (config.paths?.tokens && dirname(config.paths.tokens));
+  if (!stylesDir) {
+    throw new Error(
+      "paths.styles 또는 paths.tokens 를 설정에서 찾을 수 없어 cssBundle 기본 경로를 정할 수 없습니다.\n" +
+        "  --bundle <path> 로 명시하세요 (예: --bundle src/styles/sh-ui-components.css).",
+    );
+  }
+  return join(stylesDir, "sh-ui-components.css");
+}
+
+/**
+ * paths.components 아래 컴포넌트 폴더 (직속 디렉토리 한 단계만).
+ */
+async function listComponentDirs(componentsAbs) {
+  if (!existsSync(componentsAbs)) return [];
+  const entries = await readdir(componentsAbs, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => ({ name: e.name, dir: resolve(componentsAbs, e.name) }));
+}
+
+/**
+ * 컴포넌트 디렉토리에서 styles.css / styles.module.css 를 찾아 (있으면) 반환.
+ * .tsx 변종은 별도 — `migrateOne` 이 처리.
+ */
+function findStyleFiles(componentDir) {
+  return [
+    resolve(componentDir, "styles.css"),
+    resolve(componentDir, "styles.module.css"),
+  ].filter((p) => existsSync(p));
+}
+
+function findTsxFiles(componentDir) {
+  return [
+    resolve(componentDir, "index.tsx"),
+    resolve(componentDir, "index.module.tsx"),
+  ].filter((p) => existsSync(p));
+}
+
+export async function runMigrateBundled({ cwd, apply, bundleArg }) {
+  const { configPath, config } = await loadConfig(cwd);
+
+  if (config.cssStrategy === "bundled") {
+    console.log("이미 cssStrategy='bundled' 로 설정돼 있습니다 — 마이그레이션 불필요.");
+    return;
+  }
+
+  if ((config.cssFramework ?? "plain") !== "plain") {
+    throw new Error(
+      `cssFramework='${config.cssFramework}' 에선 bundled 모드가 동작하지 않습니다 (plain 만 지원).`,
+    );
+  }
+
+  if (config.platform !== "react") {
+    throw new Error("bundled 마이그레이션은 React 만 지원합니다.");
+  }
+
+  const componentsRel = config.paths?.components;
+  if (!componentsRel) {
+    throw new Error("paths.components 가 sh-ui.config.json 에 없습니다.");
+  }
+  const componentsAbs = resolve(cwd, componentsRel);
+  const components = await listComponentDirs(componentsAbs);
+  if (components.length === 0) {
+    console.log(`${componentsRel} 아래에 컴포넌트가 없습니다. 마이그레이션할 게 없음.`);
+  }
+
+  const bundleRel = bundleArg ?? defaultBundlePath(config);
+  const bundleAbs = resolve(cwd, bundleRel);
+
+  // 변경 매트릭스 계산
+  const plan = []; // { name, styleFiles: [], tsxFiles: [] }
+  for (const c of components) {
+    const styleFiles = findStyleFiles(c.dir);
+    const tsxFiles = findTsxFiles(c.dir);
+    if (styleFiles.length === 0 && tsxFiles.length === 0) continue;
+    plan.push({ name: c.name, dir: c.dir, styleFiles, tsxFiles });
+  }
+
+  console.log(`\n── bundled 마이그레이션 ${apply ? "(실행)" : "(dry-run)"} ──`);
+  console.log(`  bundle 파일: ${bundleRel}`);
+  console.log(`  대상 컴포넌트: ${plan.length}개`);
+  for (const p of plan) {
+    const styleNames = p.styleFiles.map((f) => relative(cwd, f));
+    const tsxNames = p.tsxFiles.map((f) => relative(cwd, f));
+    console.log(`    · ${p.name}`);
+    for (const f of styleNames) console.log(`        styles → bundle 섹션 + 파일 삭제: ${f}`);
+    for (const f of tsxNames) console.log(`        .tsx import 제거: ${f}`);
+  }
+
+  if (!apply) {
+    console.log(`\n실제 적용은 \`sh-ui migrate bundled --apply\`.`);
+    return;
+  }
+
+  // 적용 시작 — 번들 텍스트를 먼저 빌드, 마지막에 한 번에 쓴다.
+  let bundleText = existsSync(bundleAbs)
+    ? await readFile(bundleAbs, "utf8")
+    : `/* sh-ui — 컴포넌트 CSS 번들 (cssStrategy: bundled). 마커 사이는 sh-ui 가 관리, 그 밖은 사용자 자유. */\n\n`;
+
+  for (const p of plan) {
+    let cssAccum = "";
+    for (const f of p.styleFiles) {
+      const text = await readFile(f, "utf8");
+      cssAccum += (cssAccum ? "\n\n" : "") + text.trim();
+    }
+    if (cssAccum) {
+      bundleText = upsertSection(bundleText, p.name, cssAccum);
+    }
+    for (const f of p.tsxFiles) {
+      const before = await readFile(f, "utf8");
+      const after = stripStylesImport(before);
+      if (before !== after) await writeFile(f, after, "utf8");
+    }
+    for (const f of p.styleFiles) {
+      await rm(f);
+    }
+  }
+
+  await mkdir(dirname(bundleAbs), { recursive: true });
+  await writeFile(bundleAbs, bundleText, "utf8");
+
+  // config 갱신
+  const nextConfig = {
+    ...config,
+    cssStrategy: "bundled",
+    paths: { ...config.paths, cssBundle: bundleRel },
+  };
+  await writeFile(configPath, JSON.stringify(nextConfig, null, 2) + "\n", "utf8");
+
+  console.log(
+    `\n✓ 마이그레이션 완료.\n` +
+      `  bundle: ${bundleRel}\n` +
+      `  config: cssStrategy='bundled', paths.cssBundle 추가\n\n` +
+      `다음 단계: globals.css (또는 entry CSS) 에서 한 번 import 하세요:\n` +
+      `  @import './${bundleRel.replace(/^.*\//, "")}';`,
+  );
+}

package/src/theme-extract.mjs

@@ -17,6 +17,30 @@ import { resolve, relative } from "node:path";
 import { parseBlocks } from "./tokens-diff.mjs";
 import { encodeTheme } from "./create/theme/encode.js";
 
+/**
+ * Dart 의 ShUiColorTokens 필드명 ↔ TOKEN_KEYS (hyphen) 매핑.
+ * inject.js 의 DART_FIELD_SOURCES 와 같은 매핑을 reverse 로 사용.
+ */
+const DART_FIELD_TO_KEY = {
+  background: "background",
+  backgroundSubtle: "background-subtle",
+  backgroundMuted: "background-muted",
+  backgroundInverse: "background-inverse",
+  foreground: "foreground",
+  foregroundMuted: "foreground-muted",
+  foregroundSubtle: "foreground-subtle",
+  foregroundInverse: "foreground-inverse",
+  border: "border",
+  borderStrong: "border-strong",
+  primary: "primary",
+  primaryForeground: "primary-foreground",
+  primaryHover: "primary-hover",
+  danger: "danger",
+  dangerForeground: "danger-foreground",
+  dangerHover: "danger-hover",
+  ring: "ring",
+};
+
 const TOKEN_KEYS_REQUIRED = [
   "background", "background-subtle", "background-muted", "background-inverse",
   "foreground", "foreground-muted", "foreground-subtle", "foreground-inverse",
@@ -150,6 +174,79 @@ export function extractThemeFromCss(cssText) {
   };
 }
 
+/**
+ * Dart sh_ui_tokens.dart 텍스트에서 light/dark + radius 추출 → base64.
+ *
+ * 파싱 전략:
+ *   - `static const light = ShUiColorTokens(...)` 블록 찾기 (dark 도 동일)
+ *   - 본문에서 `field: Color(0xAARRGGBB)` 추출, alpha 무시 (#RRGGBB 만 인코딩)
+ *   - `static const tokens = ShUiRadiusTokens(...)` 에서 `defaultRadius: X.X,` 추출,
+ *     X.X / 16 를 rem 으로 사용 (buildTokensDart 가 rem×16 으로 픽셀화한 값)
+ */
+export function extractThemeFromDart(dartText) {
+  const light = extractDartColorBlock(dartText, "light");
+  const dark = extractDartColorBlock(dartText, "dark");
+
+  const radiusMatch = /ShUiRadiusTokens\s*\([^)]*defaultRadius:\s*(\d+(?:\.\d+)?)/s.exec(
+    dartText,
+  );
+  if (!radiusMatch) {
+    throw new Error(
+      "theme extract 실패: ShUiRadiusTokens.defaultRadius 를 찾지 못했습니다.",
+    );
+  }
+  const radiusPx = parseFloat(radiusMatch[1]);
+  const radius = Number((radiusPx / 16).toFixed(4));
+
+  const theme = { light, dark, radius };
+  const base64 = encodeTheme(theme);
+  return {
+    base64,
+    theme,
+    summary: {
+      requiredKeys: Object.keys(light).length,
+      optionalKeys: 0,
+      optionalEmitted: [],
+      radius,
+    },
+  };
+}
+
+/**
+ * `static const light = ShUiColorTokens(...)` 의 본문에서 field: hex 맵 빌드.
+ * Dart `Color(0xFFRRGGBB)` 또는 `Color(0xAARRGGBB)` (alpha 비-FF 는 의미 손실되지만
+ * sh-ui base64 는 #RRGGBB 만 지원해 alpha 잘라냄).
+ */
+function extractDartColorBlock(dartText, mode) {
+  const blockRe = new RegExp(
+    `static\\s+const\\s+${mode}\\s*=\\s*ShUiColorTokens\\s*\\(([\\s\\S]*?)\\);`,
+    "m",
+  );
+  const m = blockRe.exec(dartText);
+  if (!m) {
+    throw new Error(
+      `theme extract 실패: \`static const ${mode} = ShUiColorTokens(...)\` 블록을 찾지 못했습니다.`,
+    );
+  }
+  const body = m[1];
+  const fieldRe = /([a-zA-Z_]\w*):\s*Color\(0x([0-9a-fA-F]{8})\)/g;
+  const out = {};
+  let fm;
+  while ((fm = fieldRe.exec(body))) {
+    const field = fm[1];
+    const hexFull = fm[2].toUpperCase();
+    const key = DART_FIELD_TO_KEY[field];
+    if (!key) continue; // 알 수 없는 필드는 무시 (사용자가 ShUiColorTokens 확장한 경우)
+    out[key] = `#${hexFull.slice(2)}`;
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(
+      `theme extract 실패: ${mode} 블록에서 Color 필드를 추출하지 못했습니다.`,
+    );
+  }
+  return out;
+}
+
 async function loadConfig(cwd) {
   const configPath = resolve(cwd, "sh-ui.config.json");
   if (!existsSync(configPath)) {
@@ -162,22 +259,21 @@ async function loadConfig(cwd) {
 
 export async function runThemeExtract({ cwd, output }) {
   const config = await loadConfig(cwd);
-  if (config.platform !== "react") {
-    throw new Error(
-      `theme extract 는 React 만 지원합니다 (현재: ${config.platform}). Flutter 는 별도 도구 필요.`,
-    );
-  }
   const tokensRel = config.paths?.tokens;
   if (!tokensRel) throw new Error("paths.tokens 가 sh-ui.config.json 에 없습니다.");
   const tokensPath = resolve(cwd, tokensRel);
   if (!existsSync(tokensPath)) {
     throw new Error(
-      `tokens.css 가 없습니다 (${tokensRel}). \`sh-ui add tokens\` 로 먼저 생성하세요.`,
+      `토큰 파일이 없습니다 (${tokensRel}). \`sh-ui add tokens\` 로 먼저 생성하세요.`,
     );
   }
 
-  const cssText = await readFile(tokensPath, "utf8");
-  const { base64, summary } = extractThemeFromCss(cssText);
+  const tokensText = await readFile(tokensPath, "utf8");
+  const result =
+    config.platform === "flutter"
+      ? extractThemeFromDart(tokensText)
+      : extractThemeFromCss(tokensText);
+  const { base64, summary } = result;
 
   if (output) {
     await writeFile(resolve(cwd, output), base64 + "\n", "utf8");

package/src/tokens-cmd.mjs

@@ -15,6 +15,7 @@ import { pathToFileURL } from "node:url";
 import { getTokensRoot } from "./paths.mjs";
 import { THEME_BASES } from "./constants.js";
 import { parseBlocks, diffBlocks, applyAdditions } from "./tokens-diff.mjs";
+import { parseDartTokens, diffDartTokens } from "./tokens-diff-dart.mjs";
 
 async function loadTokensBuilder() {
   const url = pathToFileURL(resolve(getTokensRoot(), "build.mjs")).href;
@@ -48,12 +49,6 @@ async function buildExpected(config) {
         "diff/upgrade 는 base 가 neutral/zinc/slate 일 때만 사용 가능합니다.",
     );
   }
-  if (config.platform !== "react") {
-    throw new Error(
-      `tokens diff/upgrade 는 React 만 지원합니다 (현재: ${config.platform}). ` +
-        "Flutter 는 향후 추가 예정.",
-    );
-  }
   const { buildTokens } = await loadTokensBuilder();
   return buildTokens(config);
 }
@@ -74,7 +69,7 @@ function renderDiffReport({ added, removed, changed, unchangedCount }, rel) {
   console.log(`\nsh-ui tokens diff — ${rel}\n`);
 
   if (added.length === 0 && removed.length === 0 && changed.length === 0) {
-    console.log(`✓ 변경 없음 — 사용자 tokens.css 가 buildTokens 결과와 동일 (${unchangedCount} 변수).`);
+    console.log(`✓ 변경 없음 — 사용자 토큰 파일이 buildTokens 결과와 동일 (${unchangedCount} 항목).`);
     return;
   }
 
@@ -113,7 +108,10 @@ export async function runTokensDiff({ cwd }) {
   const config = await loadConfig(cwd);
   const expectedText = await buildExpected(config);
   const { text: currentText, rel } = await loadCurrent(config, cwd);
-  const diff = diffBlocks(parseBlocks(currentText), parseBlocks(expectedText));
+  const diff =
+    config.platform === "flutter"
+      ? diffDartTokens(parseDartTokens(currentText), parseDartTokens(expectedText))
+      : diffBlocks(parseBlocks(currentText), parseBlocks(expectedText));
   renderDiffReport(diff, rel);
 }
 
@@ -121,7 +119,19 @@ export async function runTokensUpgrade({ cwd, mode }) {
   const config = await loadConfig(cwd);
   const expectedText = await buildExpected(config);
   const current = await loadCurrent(config, cwd);
-  const diff = diffBlocks(parseBlocks(current.text), parseBlocks(expectedText));
+  const isFlutter = config.platform === "flutter";
+
+  if (isFlutter && mode === "apply") {
+    throw new Error(
+      "Flutter 에선 `tokens upgrade --apply` 미지원 — Dart 클래스에 필드 추가는 " +
+        "선언/생성자/static const 3 군데를 동시에 수정해야 해서 incremental 적용이 위험합니다.\n" +
+        "  대신 `sh-ui tokens upgrade --replace` 로 통째 재생성하세요.",
+    );
+  }
+
+  const diff = isFlutter
+    ? diffDartTokens(parseDartTokens(current.text), parseDartTokens(expectedText))
+    : diffBlocks(parseBlocks(current.text), parseBlocks(expectedText));
 
   console.log(`\nsh-ui tokens upgrade — ${current.rel} (${mode})\n`);
 

package/src/tokens-diff-dart.mjs

@@ -0,0 +1,147 @@
+// Flutter sh_ui_tokens.dart 와 buildTokensDart 결과를 비교한다.
+//
+// Dart 의 토큰 파일 구조:
+//   class ShUiColorTokens { final Color background; ...
+//     static const light = ShUiColorTokens(
+//       background: Color(0xFFFFFFFF),
+//       ...
+//     );
+//     static const dark = ShUiColorTokens(...);
+//   }
+//   class ShUiSpacingTokens { ...
+//     static const tokens = ShUiSpacingTokens(s0: 0.0, s1: 4.0, ...);
+//   }
+//
+// 비교 단위는 `<ClassName>.<staticName>` (예: ShUiColorTokens.light) — 그 안의
+// field: value 맵으로 평탄화 후 added / changed / removed 분류.
+//
+// Apply 정책:
+//   Dart 클래스에 새 필드 추가는 (1) class field 선언, (2) constructor 파라미터,
+//   (3) 모든 static const 인스턴스화 — 3 군데 동기 수정 필요. 위험성/구현 복잡도가
+//   CSS 마커 기반과 비교 불가. v1 Flutter 는 --replace 만 지원, --apply 는 안내 에러.
+
+/**
+ * `static const NAME = ClassName(...)` 블록들을 추출.
+ * @returns { [`ClassName.staticName`]: { field: rawValue } }
+ */
+export function parseDartTokens(dartText) {
+  const out = {};
+  // 의도적으로 단순 — `static const NAME = ClassName(...)` 의 본문 (마지막 `;` 까지) 을 캡처.
+  // 본문엔 nested 함수 호출 (Color(0x...), Cubic(...), Duration(...)) 이 가능하므로
+  // 간단한 깊이 카운터로 닫는 `)` 매칭.
+  const re = /static\s+const\s+([a-zA-Z_]\w*)\s*=\s*(ShUi[A-Z]\w*)\s*\(/g;
+  let m;
+  while ((m = re.exec(dartText))) {
+    const staticName = m[1];
+    const className = m[2];
+    const bodyStart = m.index + m[0].length;
+    const bodyEnd = findClosingParen(dartText, bodyStart);
+    if (bodyEnd < 0) continue;
+    const body = dartText.slice(bodyStart, bodyEnd);
+    const fields = parseDartFieldList(body);
+    if (Object.keys(fields).length === 0) continue;
+    out[`${className}.${staticName}`] = fields;
+  }
+  return out;
+}
+
+function findClosingParen(text, start) {
+  let depth = 1;
+  let i = start;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * `field: value, field: value, ...` 본문을 { field: value-string } 으로.
+ * 값은 trim 된 raw 문자열 — `Color(0xFF...)`, `0.5`, `Duration(milliseconds: 120)`,
+ * `Cubic(0.4, 0, 0.2, 1)`, `<BoxShadow>[...]` 등 그대로 보존.
+ */
+function parseDartFieldList(body) {
+  const out = {};
+  const items = splitByTopLevelComma(body);
+  for (const item of items) {
+    const trimmed = item.trim();
+    if (!trimmed) continue;
+    const colonIdx = findTopLevelColon(trimmed);
+    if (colonIdx < 0) continue;
+    const field = trimmed.slice(0, colonIdx).trim();
+    const value = trimmed.slice(colonIdx + 1).trim();
+    if (field && value) out[field] = value;
+  }
+  return out;
+}
+
+/** 깊이 0 콤마로 split. (), [], {} 안의 콤마는 보호. */
+function splitByTopLevelComma(text) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === "," && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/** 깊이 0 의 첫 ':' — `field: Color(0x...)` 형식 분리용. */
+function findTopLevelColon(text) {
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === ":" && depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * 두 Dart 토큰 트리 비교. CSS 측 diffBlocks 와 같은 결과 모양.
+ */
+export function diffDartTokens(currentTokens, expectedTokens) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  let unchangedCount = 0;
+
+  const allKeys = new Set([
+    ...Object.keys(currentTokens),
+    ...Object.keys(expectedTokens),
+  ]);
+
+  for (const blockKey of allKeys) {
+    const cur = currentTokens[blockKey] ?? {};
+    const exp = expectedTokens[blockKey] ?? {};
+    const fieldKeys = new Set([...Object.keys(cur), ...Object.keys(exp)]);
+    for (const field of fieldKeys) {
+      const cv = cur[field];
+      const ev = exp[field];
+      if (cv === undefined && ev !== undefined) {
+        added.push({ selector: blockKey, name: field, value: ev });
+      } else if (ev === undefined && cv !== undefined) {
+        removed.push({ selector: blockKey, name: field, value: cv });
+      } else if (cv !== ev) {
+        changed.push({ selector: blockKey, name: field, expected: ev, current: cv });
+      } else {
+        unchangedCount++;
+      }
+    }
+  }
+  return { added, removed, changed, unchangedCount };
+}