inkhouse 0.1.0-beta.0

package/src/github.ts

@@ -0,0 +1,1465 @@
+// --- GitHub API Integration ---
+// All GitHub operations are relayed through the UI iframe because the
+// Figma plugin sandbox has no direct network access.
+
+import { loadConfig, GITHUB_CONFIG } from './config';
+import {
+  TOKENS,
+  getVariableTokenDiffWithOptions,
+  tokensToCSS,
+  tokensToDTCG,
+  type ThemeTokens,
+  type TokenGroup,
+  type Tokens,
+} from './tokens';
+import { colorToLabel, debug, parseColor, mergeTokens as deepMergeTokens } from './colors';
+import { waitForUIReady } from './dev-server';
+import type { ResolvedTokenSourceMode, TokenSourceMode } from './token-source';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface GitHubFetchOptions {
+  method?: string;
+  body?: string | null;
+}
+
+interface GitHubFetchResult {
+  error?: string;
+  sha?: string;
+  object?: { sha: string };
+  content?: string;
+  tree?: { sha: string };
+  html_url?: string;
+  data?: GitHubFetchResult;
+  [key: string]: unknown;
+}
+
+interface PatchCssResult {
+  requestId: string;
+  patchedCss?: string | null;
+  source?: string;
+  error?: string | null;
+}
+
+interface FileToCommit {
+  path: string;
+  content: string;
+}
+
+interface FileContent {
+  content: string;
+  sha: string;
+}
+
+interface ClassChange {
+  property: string;
+  code?: string;
+  figma?: string;
+  newClasses?: string[];
+}
+
+interface ComponentChange {
+  name: string;
+  file?: string;
+  changes: ClassChange[];
+}
+
+interface TokenSourceInfo {
+  source: string;
+  mode: ResolvedTokenSourceMode;
+  requestedMode?: TokenSourceMode;
+}
+
+interface ResolvedCssFile {
+  path: string;
+  content: string;
+}
+
+interface TokenCommitPlan {
+  filesToCommit: FileToCommit[];
+  filesChangedLabels: string[];
+  sourceSummary: string;
+  dtcgSummary: string;
+}
+
+export interface TokenChangePreview {
+  hasChanges: boolean;
+  filesChangedLabels: string[];
+  sourceSummary: string;
+  dtcgSummary: string;
+}
+
+const TOKEN_SOURCE_INFO_KEY = 'token_source_info';
+const DEFAULT_DTCG_PATH = 'design-tokens/tokens.dtcg.json';
+const LEGACY_GENERATED_CSS_PATH = 'src/app/tokens.css';
+const CSS_DISCOVERY_PATHS = [
+  'src/app/tokens.css',
+  'src/app/globals.css',
+  'app/globals.css',
+  'styles/globals.css',
+];
+const PATCH_ENDPOINT_PORTS = [4000, 3000, 5173];
+const PATCH_ENDPOINT_PATH = '/api/figma/patch-tokens';
+
+// ---------------------------------------------------------------------------
+// Module-level state for the GitHub fetch relay
+// ---------------------------------------------------------------------------
+
+let _pendingGitHubCallbacks: Record<string, (result: GitHubFetchResult) => void> = {};
+let _githubRequestCounter = 0;
+let _pendingPatchCallbacks: Record<string, (result: PatchCssResult) => void> = {};
+let _patchRequestCounter = 0;
+
+// ---------------------------------------------------------------------------
+// GitHub fetch relay
+// ---------------------------------------------------------------------------
+
+/**
+ * Relay a GitHub API request through the UI iframe.
+ * The plugin sandbox cannot make network requests directly, so we post a
+ * message to the UI which performs the actual fetch and posts the result back.
+ */
+export async function githubFetch(
+  endpoint: string,
+  token: string,
+  options?: GitHubFetchOptions
+): Promise<GitHubFetchResult> {
+  const opts = options || {};
+  await waitForUIReady();
+
+  return new Promise<GitHubFetchResult>(function (resolve, reject) {
+    const requestId = 'github-' + ++_githubRequestCounter;
+    _pendingGitHubCallbacks[requestId] = function (result: GitHubFetchResult) {
+      if (result && result.error) {
+        reject(new Error(result.error));
+      } else {
+        resolve(result);
+      }
+    };
+
+    figma.ui.postMessage({
+      type: 'github-fetch',
+      requestId: requestId,
+      endpoint: endpoint,
+      token: token,
+      method: opts.method || 'GET',
+      body: opts.body || null,
+    });
+
+    // Timeout after 12s so UI gets feedback quickly when bridge/network is stuck.
+    setTimeout(function () {
+      if (_pendingGitHubCallbacks[requestId]) {
+        delete _pendingGitHubCallbacks[requestId];
+        reject(new Error('GitHub API request timed out for endpoint: ' + endpoint));
+      }
+    }, 12000);
+  });
+}
+
+/**
+ * Handle a GitHub fetch result message from the UI iframe.
+ * Called by the main message handler when it receives a 'github-fetch-result'.
+ */
+export function handleGitHubFetchResult(msg: { requestId: string } & GitHubFetchResult): void {
+  const cb = _pendingGitHubCallbacks[msg.requestId];
+  if (cb) {
+    delete _pendingGitHubCallbacks[msg.requestId];
+    if (msg && msg.data && typeof msg.data === 'object') {
+      cb(msg.data);
+      return;
+    }
+    cb(msg);
+  }
+}
+
+function requireResponseString(value: unknown, context: string): string {
+  if (typeof value === 'string' && value.trim().length > 0) return value;
+  throw new Error('GitHub API response missing ' + context);
+}
+
+function buildPatchEndpointCandidates(): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < PATCH_ENDPOINT_PORTS.length; i++) {
+    out.push('http://localhost:' + PATCH_ENDPOINT_PORTS[i] + PATCH_ENDPOINT_PATH);
+  }
+  return out;
+}
+
+function serializeCssUpdates(updatesByTheme: Map<string, Map<string, string>>): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = {};
+  for (const [themeName, updates] of updatesByTheme.entries()) {
+    const bucket: Record<string, string> = {};
+    for (const [prop, value] of updates.entries()) {
+      bucket[prop] = value;
+    }
+    out[themeName] = bucket;
+  }
+  return out;
+}
+
+async function patchCssViaDevServer(
+  cssPath: string,
+  cssText: string,
+  updatesByTheme: Map<string, Map<string, string>>
+): Promise<string | null> {
+  await waitForUIReady();
+
+  return new Promise<string | null>((resolve) => {
+    const requestId = 'patch-css-' + ++_patchRequestCounter;
+    _pendingPatchCallbacks[requestId] = (result: PatchCssResult) => {
+      if (result && typeof result.patchedCss === 'string') {
+        resolve(result.patchedCss);
+        return;
+      }
+      resolve(null);
+    };
+
+    figma.ui.postMessage({
+      type: 'patch-css',
+      requestId,
+      candidates: buildPatchEndpointCandidates(),
+      payload: {
+        filePath: cssPath,
+        cssText,
+        updatesByTheme: serializeCssUpdates(updatesByTheme),
+      },
+    });
+
+    setTimeout(() => {
+      if (_pendingPatchCallbacks[requestId]) {
+        delete _pendingPatchCallbacks[requestId];
+        resolve(null);
+      }
+    }, 30000);
+  });
+}
+
+/**
+ * Handle patch-css result message from UI iframe.
+ */
+export function handlePatchCssResult(msg: PatchCssResult): void {
+  const cb = _pendingPatchCallbacks[msg.requestId];
+  if (cb) {
+    delete _pendingPatchCallbacks[msg.requestId];
+    cb(msg);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Base64 encoding / decoding (works in the Figma plugin environment)
+// ---------------------------------------------------------------------------
+
+/**
+ * Encode string to base64.
+ * Handles UTF-8 by encoding to bytes first.
+ */
+export function encodeBase64(str: string): string {
+  const bytes: number[] = [];
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    if (code < 0x80) {
+      bytes.push(code);
+    } else if (code < 0x800) {
+      bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    } else {
+      bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+    }
+  }
+
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let output = '';
+  for (let j = 0; j < bytes.length; j += 3) {
+    const b1 = bytes[j];
+    const b2 = j + 1 < bytes.length ? bytes[j + 1] : 0;
+    const b3 = j + 2 < bytes.length ? bytes[j + 2] : 0;
+    output += chars.charAt(b1 >> 2);
+    output += chars.charAt(((b1 & 3) << 4) | (b2 >> 4));
+    output += j + 1 < bytes.length ? chars.charAt(((b2 & 15) << 2) | (b3 >> 6)) : '=';
+    output += j + 2 < bytes.length ? chars.charAt(b3 & 63) : '=';
+  }
+  return output;
+}
+
+/**
+ * Decode base64 string.
+ */
+export function decodeBase64(str: string): string {
+  // Remove newlines that GitHub adds
+  const cleaned = str.replace(/\n/g, '');
+
+  // Use built-in atob if available, otherwise manual decode
+  if (typeof atob === 'function') {
+    return atob(cleaned);
+  }
+
+  // Fallback: manual base64 decode
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+  let output = '';
+  let i = 0;
+
+  while (i < cleaned.length) {
+    const enc1 = chars.indexOf(cleaned.charAt(i++));
+    const enc2 = chars.indexOf(cleaned.charAt(i++));
+    const enc3 = chars.indexOf(cleaned.charAt(i++));
+    const enc4 = chars.indexOf(cleaned.charAt(i++));
+
+    const chr1 = (enc1 << 2) | (enc2 >> 4);
+    const chr2 = ((enc2 & 15) << 4) | (enc3 >> 2);
+    const chr3 = ((enc3 & 3) << 6) | enc4;
+
+    output += String.fromCharCode(chr1);
+    if (enc3 !== 64) output += String.fromCharCode(chr2);
+    if (enc4 !== 64) output += String.fromCharCode(chr3);
+  }
+
+  return output;
+}
+
+// ---------------------------------------------------------------------------
+// File content helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch file content from GitHub.
+ */
+export async function fetchFileContent(
+  token: string,
+  filePath: string,
+  branch?: string
+): Promise<FileContent | null> {
+  try {
+    const ref = branch || GITHUB_CONFIG!.baseBranch;
+    const data = await githubFetch(
+      `/repos/${GITHUB_CONFIG!.owner}/${GITHUB_CONFIG!.repo}/contents/${filePath}?ref=${ref}`,
+      token
+    );
+
+    // GitHub returns content as base64
+    let content = '';
+    if (data.content) {
+      content = decodeBase64(data.content as string);
+    }
+
+    return {
+      content: content,
+      sha: data.sha as string,
+    };
+  } catch (e: unknown) {
+    const message = e instanceof Error ? e.message : String(e);
+    debug('Failed to fetch file', filePath, message);
+    return null;
+  }
+}
+
+/**
+ * Apply class changes to a component file.
+ * Uses regex-based replacement for Tailwind classes.
+ */
+export function applyClassChangesToFile(content: string, componentChange: ComponentChange): string {
+  let updatedContent = content;
+
+  for (let i = 0; i < componentChange.changes.length; i++) {
+    const change = componentChange.changes[i];
+
+    if (change.property === 'padding') {
+      // Replace padding classes (p-X, px-X, py-X, etc.)
+      if (change.code && change.code.trim()) {
+        const oldClasses = change.code.split(' ').filter(Boolean);
+        for (let j = 0; j < oldClasses.length; j++) {
+          const oldClass = oldClasses[j];
+          const escapedOld = oldClass.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+          const regex = new RegExp('\\b' + escapedOld + '\\b', 'g');
+          if (change.newClasses && change.newClasses.length > j) {
+            updatedContent = updatedContent.replace(regex, change.newClasses[j]);
+          }
+        }
+      }
+    }
+
+    if (change.property === 'borderRadius') {
+      // Replace rounded classes
+      if (change.code && change.code.trim()) {
+        const oldRadiusClasses = change.code.split(' ').filter(Boolean);
+        for (let k = 0; k < oldRadiusClasses.length; k++) {
+          const oldRadius = oldRadiusClasses[k];
+          const escapedRadius = oldRadius.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+          const radiusRegex = new RegExp('\\b' + escapedRadius + '\\b', 'g');
+          if (change.newClasses && change.newClasses.length > k) {
+            updatedContent = updatedContent.replace(radiusRegex, change.newClasses[k]);
+          }
+        }
+      }
+    }
+  }
+
+  return updatedContent;
+}
+
+function normalizeTokenSourceInfo(raw: unknown): TokenSourceInfo {
+  const source =
+    raw && typeof raw === 'object' && typeof (raw as any).source === 'string' && (raw as any).source.trim()
+      ? (raw as any).source.trim()
+      : 'embedded:tokens.ts';
+  const modeRaw = raw && typeof raw === 'object' ? (raw as any).mode : null;
+  const mode: ResolvedTokenSourceMode =
+    modeRaw === 'css' || modeRaw === 'dtcg' || modeRaw === 'embedded' ? modeRaw : 'embedded';
+  const requestedRaw = raw && typeof raw === 'object' ? (raw as any).requestedMode : null;
+  const requestedMode: TokenSourceMode | undefined =
+    requestedRaw === 'auto' || requestedRaw === 'css' || requestedRaw === 'dtcg' ? requestedRaw : undefined;
+  return { source, mode, requestedMode };
+}
+
+async function loadTokenSourceInfo(): Promise<TokenSourceInfo> {
+  const stored = await figma.clientStorage.getAsync(TOKEN_SOURCE_INFO_KEY);
+  return normalizeTokenSourceInfo(stored);
+}
+
+function stringifyTokenValue(value: unknown): string {
+  if (typeof value === 'string') return value.trim();
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (value && typeof value === 'object') return colorToLabel(value).trim();
+  return '';
+}
+
+function parseDimensionToPx(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  const raw = String(value || '').trim().toLowerCase();
+  if (!raw) return null;
+  if (raw.endsWith('px')) {
+    const n = parseFloat(raw.slice(0, -2));
+    return Number.isFinite(n) ? n : null;
+  }
+  if (raw.endsWith('rem')) {
+    const n = parseFloat(raw.slice(0, -3));
+    return Number.isFinite(n) ? n * 16 : null;
+  }
+  if (/^-?[0-9.]+$/.test(raw)) {
+    const n = parseFloat(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function formatNumber(num: number, precision: number): string {
+  const fixed = num.toFixed(precision);
+  return fixed.replace(/\.0+$/, '').replace(/(\.\d*?)0+$/, '$1');
+}
+
+function rgbToHex(value: { r: number; g: number; b: number }): string {
+  const toHex = (n: number) => {
+    const c = Math.max(0, Math.min(255, Math.round(n * 255)));
+    return c.toString(16).padStart(2, '0');
+  };
+  return '#' + toHex(value.r) + toHex(value.g) + toHex(value.b);
+}
+
+function srgbToLinear(c: number): number {
+  if (c <= 0.04045) return c / 12.92;
+  return Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+function rgbToOklchString(value: { r: number; g: number; b: number; a?: number }, template: string): string {
+  const r = srgbToLinear(Math.max(0, Math.min(1, value.r)));
+  const g = srgbToLinear(Math.max(0, Math.min(1, value.g)));
+  const b = srgbToLinear(Math.max(0, Math.min(1, value.b)));
+
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+
+  const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const bb = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+
+  const C = Math.sqrt(a * a + bb * bb);
+  let H = Math.atan2(bb, a) * (180 / Math.PI);
+  if (H < 0) H += 360;
+
+  const usesPercentL = /oklch\(\s*[0-9.]+%/i.test(template);
+  const alpha = value.a == null ? 1 : Math.max(0, Math.min(1, value.a));
+  const includeAlpha = /\/\s*[0-9.%]+\s*\)/.test(template) || alpha < 0.999;
+
+  const lText = usesPercentL ? formatNumber(L * 100, 2) + '%' : formatNumber(L, 3);
+  const cText = formatNumber(C, 3);
+  const hText = formatNumber(H, 3);
+  if (includeAlpha) {
+    return 'oklch(' + lText + ' ' + cText + ' ' + hText + ' / ' + formatNumber(alpha, 3) + ')';
+  }
+  return 'oklch(' + lText + ' ' + cText + ' ' + hText + ')';
+}
+
+function stringifyTokenValueWithFormat(value: unknown, previousValue: unknown): string {
+  if (value && typeof value === 'object') {
+    const rgb = parseColor(value);
+    const prev = String(previousValue || '').trim();
+    if (/^oklch\(/i.test(prev)) return rgbToOklchString(rgb, prev);
+    if (/^#([0-9a-f]{3,8})$/i.test(prev)) return rgbToHex(rgb);
+    return colorToLabel(rgb).trim();
+  }
+
+  const serialized = stringifyTokenValue(value);
+  if (!serialized) return serialized;
+  const prev = String(previousValue || '').trim().toLowerCase();
+  if (!prev) return serialized;
+
+  const nextPx = parseDimensionToPx(serialized);
+  if (nextPx == null) return serialized;
+
+  if (prev.endsWith('rem')) {
+    return formatNumber(nextPx / 16, 3) + 'rem';
+  }
+  if (prev.endsWith('px')) {
+    return formatNumber(nextPx, 3) + 'px';
+  }
+  return serialized;
+}
+
+function setCssVariable(out: Map<string, string>, name: string, value: unknown, previousValue?: unknown): void {
+  const serialized = stringifyTokenValueWithFormat(value, previousValue);
+  if (!serialized) return;
+  out.set(name.startsWith('--') ? name : '--' + name, serialized);
+}
+
+function setPrefixedGroupVariables(
+  out: Map<string, string>,
+  group: TokenGroup | undefined,
+  prefix: string,
+  previousGroup?: TokenGroup
+): void {
+  if (!group) return;
+  for (const key in group) {
+    const previousValue = previousGroup ? previousGroup[key] : undefined;
+    setCssVariable(out, '--' + prefix + key, group[key], previousValue);
+  }
+}
+
+function buildThemeVariableMap(theme: ThemeTokens, previousTheme?: ThemeTokens): Map<string, string> {
+  const out = new Map<string, string>();
+  if (theme.radius) {
+    if (theme.radius.base) {
+      setCssVariable(
+        out,
+        '--radius',
+        theme.radius.base,
+        previousTheme && previousTheme.radius ? previousTheme.radius.base : undefined
+      );
+    }
+    for (const key in theme.radius) {
+      if (key === 'base') continue;
+      const prev = previousTheme && previousTheme.radius ? previousTheme.radius[key] : undefined;
+      setCssVariable(out, '--radius-' + key, theme.radius[key], prev);
+    }
+  }
+  setPrefixedGroupVariables(
+    out,
+    theme.spacing,
+    'spacing-',
+    previousTheme && previousTheme.spacing ? previousTheme.spacing : undefined
+  );
+  setPrefixedGroupVariables(
+    out,
+    theme.fontSize,
+    'text-',
+    previousTheme && previousTheme.fontSize ? previousTheme.fontSize : undefined
+  );
+  if (theme.shadow) {
+    for (const key in theme.shadow) {
+      if (key === 'DEFAULT') {
+        const prev = previousTheme && previousTheme.shadow ? previousTheme.shadow.DEFAULT : undefined;
+        setCssVariable(out, '--shadow', theme.shadow[key], prev);
+        continue;
+      }
+      const prev = previousTheme && previousTheme.shadow ? previousTheme.shadow[key] : undefined;
+      setCssVariable(out, '--shadow-' + key, theme.shadow[key], prev);
+    }
+  }
+  if (theme.font) {
+    for (const key in theme.font) {
+      const prev = previousTheme && previousTheme.font ? previousTheme.font[key] : undefined;
+      setCssVariable(out, '--font-' + key, theme.font[key], prev);
+    }
+  }
+  if (theme.color) {
+    for (const key in theme.color) {
+      const prev = previousTheme && previousTheme.color ? previousTheme.color[key] : undefined;
+      setCssVariable(out, '--' + key, theme.color[key], prev);
+    }
+  }
+  return out;
+}
+
+function buildCssVariableUpdates(tokens: Tokens, previousTokens?: Tokens): Map<string, Map<string, string>> {
+  const updates = new Map<string, Map<string, string>>();
+  const primaryTheme = (tokens.primary || {}) as ThemeTokens;
+  const previousPrimaryTheme = previousTokens && previousTokens.primary ? (previousTokens.primary as ThemeTokens) : undefined;
+  const primaryMap = buildThemeVariableMap(primaryTheme, previousPrimaryTheme);
+  if (tokens.core && tokens.core.font) {
+    for (const key in tokens.core.font) {
+      const prev = previousTokens && previousTokens.core && previousTokens.core.font ? previousTokens.core.font[key] : undefined;
+      setCssVariable(primaryMap, '--font-' + key, tokens.core.font[key], prev);
+    }
+  }
+  updates.set('primary', primaryMap);
+
+  const themeNames = Object.keys(tokens).filter((key) => key !== 'core' && key !== 'primary');
+  for (let i = 0; i < themeNames.length; i++) {
+    const themeName = themeNames[i];
+    const normalizedThemeName = String(themeName || '').trim().toLowerCase();
+    if (!normalizedThemeName || normalizedThemeName === 'primary') continue;
+    const block = tokens[themeName];
+    if (!block || typeof block !== 'object') continue;
+    const previousTheme = previousTokens && previousTokens[themeName] && typeof previousTokens[themeName] === 'object'
+      ? (previousTokens[themeName] as ThemeTokens)
+      : undefined;
+    const themeMap = buildThemeVariableMap(block as ThemeTokens, previousTheme);
+    if (themeMap.size > 0) updates.set(normalizedThemeName, themeMap);
+  }
+
+  return updates;
+}
+
+function hasTokenGroupEntries(group: unknown): boolean {
+  return !!group && typeof group === 'object' && Object.keys(group as Record<string, unknown>).length > 0;
+}
+
+function getActiveThemeNames(tokens: Tokens): Set<string> {
+  const out = new Set<string>();
+  out.add('primary');
+  const names = Object.keys(tokens || {});
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i];
+    if (!name || name === 'core') continue;
+    const block = tokens[name];
+    if (!block || typeof block !== 'object') continue;
+    const theme = block as ThemeTokens;
+    if (
+      hasTokenGroupEntries(theme.color) ||
+      hasTokenGroupEntries(theme.radius) ||
+      hasTokenGroupEntries(theme.font) ||
+      hasTokenGroupEntries(theme.spacing) ||
+      hasTokenGroupEntries(theme.fontSize) ||
+      hasTokenGroupEntries(theme.shadow)
+    ) {
+      out.add(name.toLowerCase());
+    }
+  }
+  return out;
+}
+
+function parseRuleThemeNames(selector: string): string[] {
+  const themes = new Set<string>();
+  const normalized = String(selector || '').trim().toLowerCase();
+  if (!normalized) return [];
+
+  const dataThemeMatches = normalized.matchAll(/\[data-theme\s*=\s*["']?([^"'\\\]]+)["']?\]/g);
+  for (const match of dataThemeMatches) {
+    const name = String(match[1] || '').trim();
+    if (name) themes.add(name);
+  }
+
+  if (/(\.|:)(dark)\b/.test(normalized)) themes.add('dark');
+  if (normalized.includes(':root') && themes.size === 0) themes.add('primary');
+  return Array.from(themes);
+}
+
+function cloneCssVariableUpdates(
+  updatesByTheme: Map<string, Map<string, string>>
+): Map<string, Map<string, string>> {
+  const out = new Map<string, Map<string, string>>();
+  for (const [theme, updates] of updatesByTheme.entries()) {
+    const normalizedTheme = String(theme || '').trim().toLowerCase();
+    if (!normalizedTheme) continue;
+    const existing = out.get(normalizedTheme) || new Map<string, string>();
+    for (const [prop, value] of updates.entries()) {
+      existing.set(prop, value);
+    }
+    out.set(normalizedTheme, existing);
+  }
+  return out;
+}
+
+interface CssRuleBlock {
+  selector: string;
+  body: string;
+  fullStart: number;
+  fullEnd: number;
+  bodyStart: number;
+  bodyEnd: number;
+}
+
+function escapeRegex(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function findRuleBlocks(cssText: string): CssRuleBlock[] {
+  const blocks: CssRuleBlock[] = [];
+  const ruleRegex = /([^{}]+)\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null = null;
+  while ((match = ruleRegex.exec(cssText)) != null) {
+    const selectorRaw = match[1] || '';
+    const bodyRaw = match[2] || '';
+    const selector = selectorRaw.trim();
+    if (!selector) continue;
+    const fullStart = match.index;
+    const bodyStart = fullStart + selectorRaw.length + 1;
+    blocks.push({
+      selector,
+      body: bodyRaw,
+      fullStart,
+      fullEnd: fullStart + match[0].length,
+      bodyStart,
+      bodyEnd: bodyStart + bodyRaw.length,
+    });
+  }
+  return blocks;
+}
+
+function resolveThemesForSelector(selector: string): string[] {
+  if (/^@theme\b/i.test(selector.trim())) return ['primary'];
+  return parseRuleThemeNames(selector);
+}
+
+function patchDeclarationsInBody(
+  body: string,
+  updates: Map<string, string>
+): { nextBody: string; replacedProps: string[] } {
+  if (updates.size === 0) return { nextBody: body, replacedProps: [] };
+  let nextBody = body;
+  const replacedProps: string[] = [];
+  for (const [prop, value] of updates.entries()) {
+    // Match complete custom-property declarations in a block body.
+    // Using a declaration boundary (line start / semicolon) avoids partial matches
+    // like `--primary` inside `--primary-foreground`.
+    const declarationRegex = new RegExp(
+      '(^|[;\\n\\r])([ \\t]*' + escapeRegex(prop) + '(?![a-zA-Z0-9_-])\\s*:\\s*)([^;]*)(;)',
+      'g'
+    );
+    let replaced = false;
+    nextBody = nextBody.replace(declarationRegex, function (_match, boundary, prefix, _oldValue, suffix) {
+      replaced = true;
+      return boundary + prefix + value + suffix;
+    });
+    if (replaced) replacedProps.push(prop);
+  }
+  return { nextBody, replacedProps };
+}
+
+function appendDeclarationsToBody(body: string, updates: Map<string, string>): string {
+  if (updates.size === 0) return body;
+  const indentMatch = body.match(/\n([ \t]*)--[a-z0-9-]+\s*:/i);
+  const indent = indentMatch ? indentMatch[1] : '  ';
+  let nextBody = body;
+  if (nextBody.length > 0 && !nextBody.endsWith('\n')) nextBody += '\n';
+  for (const [prop, value] of updates.entries()) {
+    nextBody += indent + prop + ': ' + value + ';\n';
+  }
+  return nextBody;
+}
+
+function replaceRange(text: string, start: number, end: number, replacement: string): string {
+  return text.slice(0, start) + replacement + text.slice(end);
+}
+
+function findFirstBlockForTheme(cssText: string, themeName: string): CssRuleBlock | null {
+  const blocks = findRuleBlocks(cssText);
+  for (let i = 0; i < blocks.length; i++) {
+    const themes = resolveThemesForSelector(blocks[i].selector);
+    for (let t = 0; t < themes.length; t++) {
+      if (themes[t] === themeName) return blocks[i];
+    }
+  }
+  return null;
+}
+
+/**
+ * Patch CSS custom properties in-place while preserving existing file structure.
+ */
+export function patchCssVariables(
+  cssText: string,
+  updatesByTheme: Map<string, Map<string, string>>,
+  activeThemeNames?: Set<string>
+  ,
+  fullThemeUpdatesByTheme?: Map<string, Map<string, string>>
+): string {
+  let nextCss = cssText;
+  const pending = cloneCssVariableUpdates(updatesByTheme);
+  const fullThemeUpdates = fullThemeUpdatesByTheme
+    ? cloneCssVariableUpdates(fullThemeUpdatesByTheme)
+    : null;
+  const blocks = findRuleBlocks(nextCss);
+
+  // Remove stale theme blocks first so renamed themes do not accumulate.
+  if (activeThemeNames && activeThemeNames.size > 0) {
+    for (let i = blocks.length - 1; i >= 0; i--) {
+      const block = blocks[i];
+      const themes = resolveThemesForSelector(block.selector);
+      if (themes.length !== 1) continue;
+      const themeName = String(themes[0] || '').toLowerCase();
+      if (!themeName || themeName === 'primary') continue;
+      if (activeThemeNames.has(themeName)) continue;
+      nextCss = replaceRange(nextCss, block.fullStart, block.fullEnd, '');
+    }
+  }
+
+  const patchedBlocks = findRuleBlocks(nextCss);
+
+  for (let i = patchedBlocks.length - 1; i >= 0; i--) {
+    const block = patchedBlocks[i];
+    const themes = resolveThemesForSelector(block.selector);
+    if (themes.length === 0) continue;
+
+    let body = block.body;
+    let changed = false;
+    for (let t = 0; t < themes.length; t++) {
+      const updates = pending.get(String(themes[t] || '').toLowerCase());
+      if (!updates || updates.size === 0) continue;
+      const patched = patchDeclarationsInBody(body, updates);
+      if (patched.replacedProps.length > 0) {
+        body = patched.nextBody;
+        changed = true;
+        for (let p = 0; p < patched.replacedProps.length; p++) {
+          updates.delete(patched.replacedProps[p]);
+        }
+      }
+    }
+    if (!changed) continue;
+    nextCss = replaceRange(nextCss, block.bodyStart, block.bodyEnd, body);
+  }
+
+  for (const [themeName, updates] of pending.entries()) {
+    if (updates.size === 0) continue;
+
+    const target = findFirstBlockForTheme(nextCss, themeName);
+    if (target) {
+      const bodyWithNewDeclarations = appendDeclarationsToBody(target.body, updates);
+      nextCss = replaceRange(nextCss, target.bodyStart, target.bodyEnd, bodyWithNewDeclarations);
+      updates.clear();
+      continue;
+    }
+
+    const selector = themeName === 'primary' ? ':root' : ':root[data-theme="' + themeName + '"]';
+    const completeThemeUpdates =
+      fullThemeUpdates && fullThemeUpdates.get(themeName)
+        ? new Map(fullThemeUpdates.get(themeName) as Map<string, string>)
+        : null;
+    const blockUpdates = completeThemeUpdates && completeThemeUpdates.size > 0 ? completeThemeUpdates : updates;
+    const newBlock = appendDeclarationsToBody('', blockUpdates);
+    const suffix = nextCss.endsWith('\n') ? '' : '\n';
+    nextCss += suffix + selector + ' {\n' + newBlock + '}\n';
+    updates.clear();
+  }
+
+  return nextCss;
+}
+
+function normalizePath(pathValue: string | undefined, fallback: string): string {
+  if (!pathValue || !pathValue.trim()) return fallback;
+  return pathValue.trim();
+}
+
+function normalizeTextForCompare(content: string): string {
+  return content.replace(/\r\n/g, '\n');
+}
+
+function uniquePaths(paths: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (let i = 0; i < paths.length; i++) {
+    const candidate = String(paths[i] || '').trim();
+    if (!candidate || seen.has(candidate)) continue;
+    seen.add(candidate);
+    out.push(candidate);
+  }
+  return out;
+}
+
+function buildCssPathCandidates(sourceInfo: TokenSourceInfo): string[] {
+  const candidates: string[] = [];
+  if (GITHUB_CONFIG && GITHUB_CONFIG.cssTokenPath) candidates.push(GITHUB_CONFIG.cssTokenPath);
+  if (sourceInfo.source && sourceInfo.source.endsWith('.css') && !sourceInfo.source.startsWith('embedded:')) {
+    candidates.push(sourceInfo.source);
+  }
+  for (let i = 0; i < CSS_DISCOVERY_PATHS.length; i++) {
+    candidates.push(CSS_DISCOVERY_PATHS[i]);
+  }
+  return uniquePaths(candidates);
+}
+
+async function resolveExistingCssFile(token: string, sourceInfo: TokenSourceInfo): Promise<ResolvedCssFile | null> {
+  const candidates = buildCssPathCandidates(sourceInfo);
+  for (let i = 0; i < candidates.length; i++) {
+    const path = candidates[i];
+    const content = await fetchFileContent(token, path, GITHUB_CONFIG!.baseBranch);
+    if (!content) continue;
+    return { path, content: content.content };
+  }
+  return null;
+}
+
+function queueFileIfChanged(
+  path: string,
+  nextContent: string,
+  previousContent: string | null,
+  filesToCommit: FileToCommit[],
+  filesChangedLabels: string[]
+): boolean {
+  if (previousContent != null) {
+    const same = normalizeTextForCompare(previousContent) === normalizeTextForCompare(nextContent);
+    if (same) return false;
+  }
+  filesToCommit.push({ path, content: nextContent });
+  filesChangedLabels.push('`' + path + '`');
+  return true;
+}
+
+function resolveConfiguredMode(mode: unknown): TokenSourceMode {
+  if (mode === 'css' || mode === 'dtcg' || mode === 'auto') return mode;
+  return 'auto';
+}
+
+async function buildTokenCommitPlan(token: string): Promise<TokenCommitPlan> {
+  const tokensBeforeVariablePatch = JSON.parse(JSON.stringify(TOKENS)) as Tokens;
+
+  // Build a minimal diff patch from current Figma Variables first.
+  // This avoids rewriting untouched tokens and keeps push diffs focused.
+  const variableDiffOptions = {
+    allowNewTokensFromFigma: GITHUB_CONFIG!.allowNewTokensFromFigma === true,
+    newTokenPrefixes: Array.isArray((GITHUB_CONFIG as any).newTokenPrefixes)
+      ? ((GITHUB_CONFIG as any).newTokenPrefixes as string[])
+      : [],
+  };
+  const variableTokenPatch = getVariableTokenDiffWithOptions(variableDiffOptions);
+  const workingTokens = variableTokenPatch
+    ? (deepMergeTokens(tokensBeforeVariablePatch as unknown, variableTokenPatch as unknown) as Tokens)
+    : tokensBeforeVariablePatch;
+
+  const sourceInfo = await loadTokenSourceInfo();
+  const configuredMode = resolveConfiguredMode(GITHUB_CONFIG!.tokenSourceMode);
+  const dtcgPath = normalizePath(GITHUB_CONFIG!.tokenPath, DEFAULT_DTCG_PATH);
+  const dtcgExisting = await fetchFileContent(token, dtcgPath, GITHUB_CONFIG!.baseBranch);
+
+  const preferDtcg =
+    configuredMode === 'dtcg' ||
+    (configuredMode === 'auto' && sourceInfo.mode === 'dtcg');
+
+  if (preferDtcg) {
+    const dtcg = tokensToDTCG(workingTokens);
+    const dtcgContent = JSON.stringify(dtcg, null, 2) + '\n';
+    const cssContent = tokensToCSS(workingTokens);
+    const cssExisting = await fetchFileContent(token, LEGACY_GENERATED_CSS_PATH, GITHUB_CONFIG!.baseBranch);
+    const filesToCommit: FileToCommit[] = [];
+    const filesChangedLabels: string[] = [];
+    queueFileIfChanged(dtcgPath, dtcgContent, dtcgExisting ? dtcgExisting.content : null, filesToCommit, filesChangedLabels);
+    queueFileIfChanged(
+      LEGACY_GENERATED_CSS_PATH,
+      cssContent,
+      cssExisting ? cssExisting.content : null,
+      filesToCommit,
+      filesChangedLabels
+    );
+    return {
+      filesToCommit,
+      filesChangedLabels,
+      sourceSummary: 'Token source: ' + dtcgPath + ' (' + configuredMode + ', resolved dtcg)',
+      dtcgSummary: 'DTCG sync: included (dtcg mode)',
+    };
+  }
+
+  const cssFile = await resolveExistingCssFile(token, sourceInfo);
+  if (!cssFile) {
+    if (configuredMode === 'css') {
+      throw new Error(
+        'CSS token source not found. Set "CSS Token Path" in settings or add one of: ' +
+          CSS_DISCOVERY_PATHS.join(', ')
+      );
+    }
+    // auto fallback when CSS file cannot be resolved but DTCG exists
+    if (dtcgExisting) {
+      const fallbackDtcg = tokensToDTCG(workingTokens);
+      const fallbackDtcgContent = JSON.stringify(fallbackDtcg, null, 2) + '\n';
+      const fallbackCssContent = tokensToCSS(workingTokens);
+      const cssExisting = await fetchFileContent(token, LEGACY_GENERATED_CSS_PATH, GITHUB_CONFIG!.baseBranch);
+      const filesToCommit: FileToCommit[] = [];
+      const filesChangedLabels: string[] = [];
+      queueFileIfChanged(
+        dtcgPath,
+        fallbackDtcgContent,
+        dtcgExisting.content,
+        filesToCommit,
+        filesChangedLabels
+      );
+      queueFileIfChanged(
+        LEGACY_GENERATED_CSS_PATH,
+        fallbackCssContent,
+        cssExisting ? cssExisting.content : null,
+        filesToCommit,
+        filesChangedLabels
+      );
+      return {
+        filesToCommit,
+        filesChangedLabels,
+        sourceSummary: 'Token source: ' + dtcgPath + ' (' + configuredMode + ', resolved dtcg)',
+        dtcgSummary: 'DTCG sync: included (auto fallback to dtcg)',
+      };
+    }
+    throw new Error('No token source file found in repository for current settings.');
+  }
+
+  const updates = buildCssVariableUpdates(variableTokenPatch || ({} as Tokens), tokensBeforeVariablePatch);
+  const fullThemeUpdates = buildCssVariableUpdates(workingTokens, tokensBeforeVariablePatch);
+  const activeThemeNames = getActiveThemeNames(workingTokens);
+  let patchedCss = await patchCssViaDevServer(cssFile.path, cssFile.content, updates);
+  if (typeof patchedCss !== 'string') {
+    // Dev server route unavailable or invalid response: fallback to in-plugin patcher.
+    patchedCss = patchCssVariables(cssFile.content, updates, activeThemeNames, fullThemeUpdates);
+  } else {
+    // Keep stale-theme pruning/add-missing-theme deterministic even when server route handled declaration patching.
+    patchedCss = patchCssVariables(patchedCss, updates, activeThemeNames, fullThemeUpdates);
+  }
+  const filesToCommit: FileToCommit[] = [];
+  const filesChangedLabels: string[] = [];
+  queueFileIfChanged(cssFile.path, patchedCss, cssFile.content, filesToCommit, filesChangedLabels);
+
+  let dtcgSummary = 'DTCG sync: skipped (syncDtcgOnPush=false)';
+  if (GITHUB_CONFIG!.syncDtcgOnPush) {
+    if (!dtcgExisting) {
+      dtcgSummary = 'DTCG sync: skipped (DTCG file not found)';
+    } else {
+      const dtcg = tokensToDTCG(workingTokens);
+      const dtcgContent = JSON.stringify(dtcg, null, 2) + '\n';
+      const changed = queueFileIfChanged(
+        dtcgPath,
+        dtcgContent,
+        dtcgExisting.content,
+        filesToCommit,
+        filesChangedLabels
+      );
+      dtcgSummary = changed
+        ? 'DTCG sync: included (' + dtcgPath + ')'
+        : 'DTCG sync: no changes (' + dtcgPath + ')';
+    }
+  }
+
+  return {
+    filesToCommit,
+    filesChangedLabels,
+    sourceSummary: 'Token source: ' + cssFile.path + ' (' + configuredMode + ', resolved css)',
+    dtcgSummary,
+  };
+}
+
+export async function previewTokenChanges(token: string): Promise<TokenChangePreview> {
+  await loadConfig();
+  const plan = await buildTokenCommitPlan(token);
+  return {
+    hasChanges: plan.filesToCommit.length > 0,
+    filesChangedLabels: plan.filesChangedLabels.slice(),
+    sourceSummary: plan.sourceSummary,
+    dtcgSummary: plan.dtcgSummary,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GitHub API operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the SHA of a file on a given branch. Returns null if the file does not exist.
+ */
+export async function getFileSha(
+  token: string,
+  path: string,
+  branch?: string
+): Promise<string | null> {
+  try {
+    const ref = branch || GITHUB_CONFIG!.baseBranch;
+    const data = await githubFetch(
+      `/repos/${GITHUB_CONFIG!.owner}/${GITHUB_CONFIG!.repo}/contents/${path}?ref=${ref}`,
+      token
+    );
+    if (typeof data.sha === 'string' && data.sha.trim().length > 0) return data.sha;
+    return null;
+  } catch (_e) {
+    // File doesn't exist yet
+    return null;
+  }
+}
+
+/**
+ * Get the latest commit SHA on the base branch.
+ */
+export async function getLatestCommitSha(token: string): Promise<string> {
+  const data = await githubFetch(
+    `/repos/${GITHUB_CONFIG!.owner}/${GITHUB_CONFIG!.repo}/git/ref/heads/${GITHUB_CONFIG!.baseBranch}`,
+    token
+  );
+  return requireResponseString(data.object && data.object.sha, 'object.sha from branch ref');
+}
+
+/**
+ * Create a new branch from a given SHA.
+ */
+export async function createBranch(
+  token: string,
+  branchName: string,
+  fromSha: string
+): Promise<void> {
+  await githubFetch(
+    `/repos/${GITHUB_CONFIG!.owner}/${GITHUB_CONFIG!.repo}/git/refs`,
+    token,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        ref: `refs/heads/${branchName}`,
+        sha: fromSha,
+      }),
+    }
+  );
+}
+
+/**
+ * Create or update a single file via the Contents API.
+ */
+export async function createOrUpdateFile(
+  token: string,
+  path: string,
+  content: string,
+  message: string,
+  branch: string,
+  sha?: string | null
+): Promise<void> {
+  const body: Record<string, string> = {
+    message,
+    content: encodeBase64(content),
+    branch,
+  };
+  if (sha) body.sha = sha;
+
+  await githubFetch(
+    `/repos/${GITHUB_CONFIG!.owner}/${GITHUB_CONFIG!.repo}/contents/${path}`,
+    token,
+    {
+      method: 'PUT',
+      body: JSON.stringify(body),
+    }
+  );
+}
+
+/**
+ * Commit multiple files in a single commit using the Git Data API.
+ * Avoids SHA race conditions when committing files sequentially via the Contents API.
+ *
+ * @param token - GitHub token
+ * @param files - files to commit
+ * @param message - commit message
+ * @param branchRef - full ref e.g. 'heads/figma/tokens-...'
+ * @param baseSha - commit SHA to base the new commit on
+ * @returns the new commit SHA
+ */
+export async function commitMultipleFiles(
+  token: string,
+  files: FileToCommit[],
+  message: string,
+  branchRef: string,
+  baseSha: string
+): Promise<string> {
+  const repoBase = '/repos/' + GITHUB_CONFIG!.owner + '/' + GITHUB_CONFIG!.repo;
+
+  // 1. Create a blob for each file
+  const treeItems: Array<{ path: string; mode: string; type: string; sha: string }> = [];
+  for (let i = 0; i < files.length; i++) {
+    const blob = await githubFetch(repoBase + '/git/blobs', token, {
+      method: 'POST',
+      body: JSON.stringify({
+        content: files[i].content,
+        encoding: 'utf-8',
+      }),
+    });
+    const blobSha = requireResponseString(blob.sha, 'sha from blob creation for ' + files[i].path);
+    treeItems.push({
+      path: files[i].path,
+      mode: '100644',
+      type: 'blob',
+      sha: blobSha,
+    });
+  }
+
+  // 2. Create a new tree based on the base commit's tree
+  const baseCommit = await githubFetch(repoBase + '/git/commits/' + baseSha, token);
+  const baseTreeSha = requireResponseString(baseCommit.tree && baseCommit.tree.sha, 'tree.sha from base commit');
+  const newTree = await githubFetch(repoBase + '/git/trees', token, {
+    method: 'POST',
+    body: JSON.stringify({
+      base_tree: baseTreeSha,
+      tree: treeItems,
+    }),
+  });
+  const newTreeSha = requireResponseString(newTree.sha, 'sha from tree creation');
+
+  // 3. Create a new commit
+  const newCommit = await githubFetch(repoBase + '/git/commits', token, {
+    method: 'POST',
+    body: JSON.stringify({
+      message: message,
+      tree: newTreeSha,
+      parents: [baseSha],
+    }),
+  });
+  const newCommitSha = requireResponseString(newCommit.sha, 'sha from commit creation');
+
+  // 4. Update the branch ref to point to the new commit
+  await githubFetch(repoBase + '/git/refs/' + branchRef, token, {
+    method: 'PATCH',
+    body: JSON.stringify({
+      sha: newCommitSha,
+    }),
+  });
+
+  return newCommitSha;
+}
+
+/**
+ * Create a pull request and return its URL.
+ */
+export async function createPullRequest(
+  token: string,
+  branchName: string,
+  title: string,
+  body: string
+): Promise<string> {
+  const data = await githubFetch(
+    `/repos/${GITHUB_CONFIG!.owner}/${GITHUB_CONFIG!.repo}/pulls`,
+    token,
+    {
+      method: 'POST',
+      body: JSON.stringify({
+        title,
+        body,
+        head: branchName,
+        base: GITHUB_CONFIG!.baseBranch,
+      }),
+    }
+  );
+  return requireResponseString(data.html_url, 'html_url from pull request creation');
+}
+
+// ---------------------------------------------------------------------------
+// High-level push flows
+// ---------------------------------------------------------------------------
+
+/**
+ * Main token push flow: extract tokens, commit all derived files, and open a PR.
+ */
+export async function pushToGitHub(
+  commitMessage: string,
+  prDescription?: string
+): Promise<string> {
+  // Load config
+  await loadConfig();
+
+  // Validate config
+  if (!GITHUB_CONFIG!.owner || !GITHUB_CONFIG!.repo) {
+    throw new Error('Repository not configured. Go to Settings to configure owner/repo.');
+  }
+
+  const token = await figma.clientStorage.getAsync('github_token') as string;
+  if (!token) {
+    throw new Error('GitHub token not configured. Please configure your token first.');
+  }
+
+  const tokenPlan = await buildTokenCommitPlan(token);
+  if (tokenPlan.filesToCommit.length === 0) {
+    throw new Error('No token changes detected for the configured token source.');
+  }
+
+  // Generate branch name
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const branchName = 'figma/tokens-' + timestamp;
+
+  // Get latest commit SHA
+  const latestSha = await getLatestCommitSha(token);
+
+  // Create new branch
+  await createBranch(token, branchName, latestSha);
+
+  await commitMultipleFiles(token, tokenPlan.filesToCommit, commitMessage, 'heads/' + branchName, latestSha);
+
+  // Create PR
+  const projectLabel = GITHUB_CONFIG!.projectName || (GITHUB_CONFIG!.owner + '/' + GITHUB_CONFIG!.repo);
+  const changedLines =
+    tokenPlan.filesChangedLabels.length > 0
+      ? tokenPlan.filesChangedLabels.map((label) => '- Updated ' + label).join('\n')
+      : '- No token files changed';
+  const prBody =
+    '## Design Token Update\n\n' +
+    (prDescription || 'Updated design tokens from Figma.') +
+    '\n\n' +
+    '### Changes\n' +
+    changedLines +
+    '\n\n' +
+    '### Token Source\n' +
+    '- ' + tokenPlan.sourceSummary + '\n' +
+    '- ' + tokenPlan.dtcgSummary + '\n\n' +
+    '---\n' +
+    '*Auto-generated from ' + projectLabel + ' Figma plugin*';
+
+  const prUrl = await createPullRequest(token, branchName, commitMessage, prBody);
+  return prUrl;
+}
+
+/**
+ * Extended push flow with component file changes.
+ * Commits token updates and component style patches in separate commits on the same branch.
+ */
+export async function pushToGitHubWithComponents(
+  commitMessage: string,
+  prDescription: string | undefined,
+  includeTokens: boolean,
+  componentChanges: ComponentChange[],
+  onProgress?: (message: string) => void
+): Promise<string> {
+  const progress = typeof onProgress === 'function' ? onProgress : (_message: string) => {};
+
+  // Load config
+  progress('Loading configuration...');
+  await loadConfig();
+
+  // Validate config
+  progress('Validating repository settings...');
+  if (!GITHUB_CONFIG!.owner || !GITHUB_CONFIG!.repo) {
+    throw new Error('Repository not configured. Go to Settings to configure owner/repo.');
+  }
+
+  const token = await figma.clientStorage.getAsync('github_token') as string;
+  if (!token) {
+    throw new Error('GitHub token not configured. Please configure your token first.');
+  }
+
+  // Generate branch name
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const branchName = 'figma/design-update-' + timestamp;
+
+  // Get latest commit SHA
+  progress('Fetching latest commit...');
+  let latestSha = await getLatestCommitSha(token);
+
+  // Create new branch
+  progress('Creating branch...');
+  await createBranch(token, branchName, latestSha);
+
+  const filesChanged: string[] = [];
+  let tokenPlan: TokenCommitPlan | null = null;
+
+  // 1. Update tokens if requested
+  if (includeTokens) {
+    progress('Preparing token updates...');
+    tokenPlan = await buildTokenCommitPlan(token);
+    if (tokenPlan.filesToCommit.length > 0) {
+      progress('Committing token updates...');
+      const newCommitSha = await commitMultipleFiles(
+        token,
+        tokenPlan.filesToCommit,
+        commitMessage,
+        'heads/' + branchName,
+        latestSha
+      );
+      latestSha = newCommitSha;
+      for (let i = 0; i < tokenPlan.filesChangedLabels.length; i++) {
+        filesChanged.push(tokenPlan.filesChangedLabels[i]);
+      }
+    }
+  }
+
+  // 2. Update component files (batch into a single commit)
+  const componentUpdates: Array<{ name: string; changes: ClassChange[] }> = [];
+  const componentFiles: FileToCommit[] = [];
+
+  for (let i = 0; i < componentChanges.length; i++) {
+    const change = componentChanges[i];
+    if (!change.file) continue;
+
+    try {
+      // Fetch current file content from base branch (unchanged by token commit)
+      const fileData = await fetchFileContent(token, change.file, GITHUB_CONFIG!.baseBranch);
+      if (!fileData) continue;
+
+      const content = fileData.content;
+
+      // Apply class changes
+      const updatedContent = applyClassChangesToFile(content, change);
+
+      if (updatedContent !== content) {
+        componentFiles.push({ path: change.file, content: updatedContent });
+        filesChanged.push('`' + change.file + '`');
+        componentUpdates.push({
+          name: change.name,
+          changes: change.changes,
+        });
+      }
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      debug('Failed to update component file', change.file, message);
+      // Continue with other files
+    }
+  }
+
+  if (componentFiles.length > 0) {
+    progress('Committing component updates...');
+    const compCommitSha = await commitMultipleFiles(
+      token,
+      componentFiles,
+      'Update component styles from Figma',
+      'heads/' + branchName,
+      latestSha
+    );
+    latestSha = compCommitSha;
+  }
+
+  if (filesChanged.length === 0) {
+    throw new Error('No token or component changes detected to commit.');
+  }
+
+  // 3. Create PR with detailed description
+  const projectLabel = GITHUB_CONFIG!.projectName || (GITHUB_CONFIG!.owner + '/' + GITHUB_CONFIG!.repo);
+
+  const prBodyParts: string[] = ['## Design System Update\n'];
+  prBodyParts.push((prDescription || 'Updated design system from Figma.') + '\n');
+
+  prBodyParts.push('### Files Changed\n');
+  for (let j = 0; j < filesChanged.length; j++) {
+    prBodyParts.push('- ' + filesChanged[j] + '\n');
+  }
+
+  if (componentUpdates.length > 0) {
+    prBodyParts.push('\n### Component Updates\n');
+    for (let k = 0; k < componentUpdates.length; k++) {
+      const update = componentUpdates[k];
+      prBodyParts.push('\n**' + update.name + '**\n');
+      for (let l = 0; l < update.changes.length; l++) {
+        const ch = update.changes[l];
+        prBodyParts.push('- ' + ch.property + ': `' + ch.code + '` → `' + ch.figma + '`\n');
+      }
+    }
+  }
+
+  if (includeTokens && tokenPlan) {
+    prBodyParts.push('\n### Token Source\n');
+    prBodyParts.push('- ' + tokenPlan.sourceSummary + '\n');
+    prBodyParts.push('- ' + tokenPlan.dtcgSummary + '\n');
+  }
+
+  prBodyParts.push('\n---\n');
+  prBodyParts.push('*Auto-generated from ' + projectLabel + ' Figma plugin*');
+
+  const prBody = prBodyParts.join('');
+  progress('Creating pull request...');
+  const prUrl = await createPullRequest(token, branchName, commitMessage, prBody);
+  progress('Pull request created.');
+  return prUrl;
+}