inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/src/main.ts

@@ -3,24 +3,147 @@
 // Includes "Push to Code" feature for GitHub PR creation.
 // Universal plugin - configure for any project via Settings.
 
-import { loadConfig, saveConfig, GITHUB_CONFIG } from './config';
+import { loadConfig, saveConfig, GITHUB_CONFIG } from './plugin';
 import { TOKENS, COMPONENT_DEFS, applyScannedTokens, getCoreFontFamily, getThemeFontFamily, getThemeNames } from './tokens';
-import { rebuildColorIndex } from './colors';
-import { handleUIReady, handleImageResult, prefetchImages } from './dev-server';
-import { setImageMap, setSvgMap } from './image-cache';
-import { applyPack, type Pack } from './packs';
-import { handlePackResult, refreshPack } from './pack-provider';
-import { createOrUpdateStyles } from './variables';
+import { rebuildColorIndex } from './tokens';
+import { handleUIReady, handleImageResult, prefetchImages } from './plugin';
+import { setImageMap, setSvgMap } from './cache';
+import { applyPack, type Pack, handlePackResult, refreshPack } from './plugin';
+import { createOrUpdateStyles } from './tokens';
 import { tailwindForNode } from './tailwind';
-import { detectComponentChanges } from './change-detection';
+import { detectComponentChanges } from './tokens';
 import { pushToGitHub, pushToGitHubWithComponents, handleGitHubFetchResult, handlePatchCssResult, previewTokenChanges } from './github';
-import { buildDesignSystemSinglePage } from './design-system';
-import { waitForAllFonts } from './text-builder';
-import { getKnownStylesForFamily, initializeFontStyleIndex } from './font-style-resolver';
-import type { ResolvedTokenSourceMode, ScannedTokenMap, TokenSourceMode } from './token-source';
+import {
+  buildDesignSystemSinglePage,
+  cleanGeneratedDesignSystemArtifacts,
+  computePreflightData,
+  isGeneratedDesignSystemNode,
+} from './design-system';
+import { hashString, stableStringify, getFrameHash, findChildByName } from './cache';
+import { waitForAllFonts } from './text';
+import { getKnownStylesForFamily, initializeFontStyleIndex } from './text';
+import type { ResolvedTokenSourceMode, ScannedTokenMap, TokenSourceMode } from './tokens';
+import { collectImageSrcs } from './plugin/image-src-collector';
 
 const PACK_LOAD_ERROR = 'Dev server not reachable / pack not found.';
+const PREFLIGHT_EXCLUDED_KEY = 'preflight_excluded_components';
+// Synthetic preflight identifier for the Design Tokens row. Kept as a constant
+// so design-system.ts and main.ts agree on the magic name. Double-underscore
+// prefix avoids collision with real component names.
+const DESIGN_TOKENS_TOGGLE = '__design_tokens__';
+
+// Loading-phase status messages render inside the plugin panel (above the
+// drop animation) instead of as Figma toasts. The panel must be visible
+// for these to be seen, so the caller is responsible for showing the
+// loading view before invoking setStatus. Errors and final success still
+// use figma.notify so they're visible even if the panel is closed.
+/**
+ * Loading-panel status. Accepts either a flat string (legacy single-line
+ * status) or `{ phase, detail }` where the phase is sticky context
+ * ("Building components") and the detail is the per-section sub-line
+ * ("Primary theme · Organisms (26)"). Both forms post a `status`
+ * message; the UI iframe renders them as one or two lines.
+ *
+ * Two yield modes:
+ *
+ * - `noYield: true` (fine-grained per-section emits) — does a
+ *   `setTimeout(0)` yield, just long enough for the iframe to drain its
+ *   postMessage queue and update the panel. Without any yield the
+ *   iframe never gets a turn while code.js holds the thread, so the
+ *   user only ever sees the parent phase ("Building components") even
+ *   though 20+ detail emits fire. With a 0ms yield the panel updates
+ *   but Figma's canvas typically can't complete a full paint pass in
+ *   that window — combined with the column visibility-toggle in
+ *   addColumn, no overlap is observable.
+ * - default (coarse phase boundaries in main.ts) — 50ms yield. Gives
+ *   the canvas a paint frame so users see progress between top-level
+ *   phases (Reading components → Building tokens → Building components).
+ */
+type StatusInput =
+  | string
+  | { phase?: string; detail?: string; noYield?: boolean };
+
+async function setStatus(input: StatusInput): Promise<void> {
+  const noYield = typeof input === 'object' && input !== null && input.noYield === true;
+  // Only include `phase` / `detail` in the message when the caller
+  // actually provided them. Sending `phase: ''` on a detail-only emit
+  // would clobber the sticky phase header in the UI — the panel relies
+  // on the absence of a `phase` key to keep the previous phase visible
+  // while detail messages cycle below.
+  //
+  // A bare string is treated as a NEW phase (sticky header) with the
+  // detail cleared. CSS animates trailing dots on the phase element, so
+  // we strip any baked-in `…` / `...` ellipsis from both phase AND
+  // detail — otherwise the visible text would carry static dots
+  // alongside the animated dots from CSS, masking the animation.
+  const stripTrailingDots = (text: string): string => text.replace(/(\u2026|\.\.\.)\s*$/, '').trim();
+  let message: {
+    type: 'status';
+    phase?: string;
+    detail?: string;
+  };
+  if (typeof input === 'string') {
+    message = { type: 'status', phase: stripTrailingDots(input), detail: '' };
+  } else {
+    message = { type: 'status' };
+    if (typeof input.phase === 'string') message.phase = stripTrailingDots(input.phase);
+    if (typeof input.detail === 'string') message.detail = stripTrailingDots(input.detail);
+  }
+  try {
+    figma.ui.postMessage(message);
+  } catch (_err) {
+    // ui not yet shown — caller should show the loading view first
+  }
+  const delay = noYield ? 0 : 50;
+  await new Promise(function (resolve) { setTimeout(resolve, delay); });
+}
+
+function clearStatus(): void {
+  try {
+    figma.ui.postMessage({ type: 'status', phase: '', detail: '' });
+  } catch (_err) {}
+}
+
+
+function errorMessage(e: unknown): string {
+  if (e instanceof Error) return errorMessage(e);
+  if (e && typeof e === 'object' && 'message' in e) return String((e as { message: unknown }).message);
+  return String(e);
+}
+
+async function loadExcludedComponents(): Promise<string[]> {
+  const docId = (figma.root && figma.root.id) ? String(figma.root.id) : '';
+  const key = docId ? PREFLIGHT_EXCLUDED_KEY + ':' + docId : PREFLIGHT_EXCLUDED_KEY;
+  try {
+    const stored = await figma.clientStorage.getAsync(key);
+    if (Array.isArray(stored)) return stored as string[];
+  } catch (_e) {}
+  return [];
+}
+
+async function saveExcludedComponents(excluded: string[]): Promise<void> {
+  const docId = (figma.root && figma.root.id) ? String(figma.root.id) : '';
+  const key = docId ? PREFLIGHT_EXCLUDED_KEY + ':' + docId : PREFLIGHT_EXCLUDED_KEY;
+  try {
+    await figma.clientStorage.setAsync(key, excluded);
+  } catch (_e) {}
+}
 const TOKEN_SOURCE_INFO_KEY = 'token_source_info';
+const DEBUG_PLUGIN_DATA_KEYS = [
+  'inkbridge:generated',
+  'inkbridge:scope',
+  'inkbridge:role',
+  'inkbridge:fallback-reason',
+  'inkbridge:hash',
+  'inkbridge:symbol-decision',
+  'inkbridge:symbol-ignored-props',
+  'inkbridge:symbol-text-overrides',
+  'inkbridge:symbol-slot-prop-mappings',
+  'inkbridge:story-name',
+  'inkbridge:story-def',
+  'inkbridge:story-scan',
+  'inkbridge:story-render',
+];
 
 type TokenSourceInfo = {
   source: string;
@@ -30,6 +153,106 @@ type TokenSourceInfo = {
 
 let LAST_TOKEN_SOURCE_INFO: TokenSourceInfo | null = null;
 
+function readNodePluginData(node: BaseNode): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!node || typeof node.getPluginData !== 'function') return out;
+  for (let i = 0; i < DEBUG_PLUGIN_DATA_KEYS.length; i++) {
+    const key = DEBUG_PLUGIN_DATA_KEYS[i];
+    try {
+      const value = node.getPluginData(key);
+      if (value) out[key] = value;
+    } catch (_err) {
+      // ignore plugin data read failures
+    }
+  }
+  return out;
+}
+
+type NodeDescription = {
+  id: string;
+  name: string;
+  type: string;
+  width?: number;
+  height?: number;
+  layoutMode?: string;
+  childCount?: number;
+  pluginData?: Record<string, string>;
+};
+
+function describeNode(node: BaseNode): NodeDescription {
+  const info: NodeDescription = {
+    id: node && node.id ? String(node.id) : '',
+    name: node && node.name ? String(node.name) : '',
+    type: node && node.type ? String(node.type) : '',
+  };
+  if (node && 'width' in node && typeof node.width === 'number') info.width = Math.round(node.width);
+  if (node && 'height' in node && typeof node.height === 'number') info.height = Math.round(node.height);
+  if (node && 'layoutMode' in node && node.layoutMode) info.layoutMode = String(node.layoutMode);
+  if (node && 'children' in node && Array.isArray(node.children)) {
+    info.childCount = node.children.length;
+  }
+  const pluginData = readNodePluginData(node);
+  if (Object.keys(pluginData).length > 0) {
+    info.pluginData = pluginData;
+  }
+  return info;
+}
+
+function collectChildrenSummary(node: BaseNode): NodeDescription[] {
+  if (!node || !('children' in node) || !Array.isArray(node.children)) return [];
+  const out: NodeDescription[] = [];
+  for (let i = 0; i < node.children.length; i++) {
+    out.push(describeNode(node.children[i]));
+  }
+  return out;
+}
+
+function findGeneratedDebugFallbackNode(): BaseNode | null {
+  const currentPage = figma.currentPage;
+  if (currentPage && isGeneratedDesignSystemNode(currentPage)) {
+    return currentPage;
+  }
+
+  if (figma.root && Array.isArray(figma.root.children)) {
+    for (let i = 0; i < figma.root.children.length; i++) {
+      const page = figma.root.children[i];
+      if (!page || page.type !== 'PAGE') continue;
+      if (isGeneratedDesignSystemNode(page)) return page;
+    }
+  }
+
+  return null;
+}
+
+function runDebugSelectionCommand(): void {
+  const selection = figma.currentPage && Array.isArray(figma.currentPage.selection)
+    ? figma.currentPage.selection
+    : [];
+  const fallbackNode = selection.length === 0 ? findGeneratedDebugFallbackNode() : null;
+  const targetNodes = selection.length > 0
+    ? selection
+    : (fallbackNode ? [fallbackNode] : []);
+  if (targetNodes.length === 0) {
+    figma.notify('No selected node and no generated Design System page found.');
+    return;
+  }
+
+  const report = targetNodes.map(function(node: BaseNode) {
+    return {
+      selected: describeNode(node),
+      children: collectChildrenSummary(node),
+    };
+  });
+
+  console.error('[Inkbridge][DebugSelection]', JSON.stringify(report, null, 2));
+  if (selection.length > 0) {
+    figma.notify('Debug report written to plugin console.');
+  } else {
+    figma.notify('Debug report written for generated Design System page.');
+  }
+}
+
+
 function getPackLoadErrorMessage(error?: string): string {
   if (error === 'incompatible-schema-version' || error === 'incompatible-pack-version') {
     return 'Incompatible scanner contract. Update plugin and scanner to matching versions.';
@@ -44,18 +267,16 @@ function isOfflineError(error?: string): boolean {
   return !error || error === 'timeout' || error === 'no-result';
 }
 
-function coerceTokenSourceInfo(raw: any): TokenSourceInfo {
+function coerceTokenSourceInfo(raw: unknown): TokenSourceInfo {
+  const obj = raw && typeof raw === 'object' ? (raw as Record<string, unknown>) : null;
+  const modeRaw = obj ? obj.mode : null;
   const mode: ResolvedTokenSourceMode =
-    raw && (raw.mode === 'css' || raw.mode === 'dtcg' || raw.mode === 'embedded')
-      ? raw.mode
-      : 'embedded';
+    modeRaw === 'css' || modeRaw === 'dtcg' || modeRaw === 'embedded' ? modeRaw : 'embedded';
+  const requestedRaw = obj ? obj.requestedMode : null;
   const requestedMode: TokenSourceMode | undefined =
-    raw && (raw.requestedMode === 'auto' || raw.requestedMode === 'css' || raw.requestedMode === 'dtcg')
-      ? raw.requestedMode
-      : undefined;
-  const source = raw && typeof raw.source === 'string' && raw.source.trim()
-    ? raw.source.trim()
-    : 'embedded:tokens.ts';
+    requestedRaw === 'css' || requestedRaw === 'dtcg' ? requestedRaw : undefined;
+  const sourceRaw = obj && typeof obj.source === 'string' ? obj.source.trim() : '';
+  const source = sourceRaw || 'embedded:tokens.ts';
   return { source, mode, requestedMode };
 }
 
@@ -83,41 +304,11 @@ async function postTokenSourceInfoToUI(): Promise<void> {
   figma.ui.postMessage({ type: 'token-source-info', info: info });
 }
 
-// ---------------------------------------------------------------------------
-// Image src collection
-// ---------------------------------------------------------------------------
-
-function collectImageSrcsFromJsxTree(node: any, out: Set<string>): void {
-  if (!node || typeof node !== 'object') return;
-  const tag = node.tagName;
-  if (tag === 'img' || tag === 'Image') {
-    const src = node.props?.src;
-    if (typeof src === 'string' && src.length > 0 && src !== 'src') {
-      out.add(src);
-    }
-  }
-  if (Array.isArray(node.children)) {
-    for (const child of node.children) collectImageSrcsFromJsxTree(child, out);
-  }
-}
-
-function collectImageSrcs(components: any[]): string[] {
-  const srcs = new Set<string>();
-  for (const comp of components) {
-    const analysis = comp?.analysis;
-    if (!analysis) continue;
-    collectImageSrcsFromJsxTree(analysis.jsxTree, srcs);
-    for (const story of analysis.stories ?? []) {
-      collectImageSrcsFromJsxTree(story.jsxTree, srcs);
-    }
-  }
-  return [...srcs];
-}
-
 // ----------------------- License Checking -----------------------
 
 let pendingLicenseResolve: ((tier: 'free' | 'pro') => void) | null = null;
 let licenseValidatingFromSettings = false;
+let sessionTier: 'free' | 'pro' | null = null;
 
 async function checkLicenseOnline(key: string): Promise<'free' | 'pro'> {
   return new Promise<'free' | 'pro'>(function(resolve) {
@@ -133,8 +324,11 @@ async function checkLicenseOnline(key: string): Promise<'free' | 'pro'> {
 }
 
 async function checkLicense(): Promise<'free' | 'pro'> {
+  // Memory cache — valid for the lifetime of this plugin session
+  if (sessionTier !== null) return sessionTier;
+
   const key = await figma.clientStorage.getAsync('license_key');
-  if (!key) return 'free';
+  if (!key) { sessionTier = 'free'; return 'free'; }
 
   const cachedTier = await figma.clientStorage.getAsync('license_tier') as string | null;
   const cachedAt = await figma.clientStorage.getAsync('license_cache_at') as string | null;
@@ -142,10 +336,13 @@ async function checkLicense(): Promise<'free' | 'pro'> {
 
   // Only trust cached 'pro' — never trust cached 'free' (avoids stale negatives)
   if (cachedTier === 'pro' && cachedAt && (Date.now() - Number(cachedAt)) < SEVEN_DAYS) {
+    sessionTier = 'pro';
     return 'pro';
   }
 
-  return checkLicenseOnline(key as string);
+  const tier = await checkLicenseOnline(key as string);
+  sessionTier = tier;
+  return tier;
 }
 
 // ----------------------- Generate Command -----------------------
@@ -184,18 +381,46 @@ async function warmThemeFonts(): Promise<string[]> {
   return failedFonts;
 }
 
+async function waitForFontsBeforeClose(timeoutMs = 4000): Promise<void> {
+  let timedOut = false;
+  await Promise.race([
+    waitForAllFonts(),
+    new Promise<void>((resolve) => {
+      setTimeout(() => {
+        timedOut = true;
+        resolve();
+      }, timeoutMs);
+    }),
+  ]);
+  if (timedOut) {
+    figma.notify('⚠️ Font load timeout; continuing.', { timeout: 2000 });
+  }
+}
+
 async function runGenerate(): Promise<void> {
   let shouldClose = true;
   try {
     await loadConfig();
-    // Show UI (hidden) so it can relay fetch requests
-    // code.js sandbox has no network access - UI iframe does the fetching
-    figma.showUI(__html__, { visible: false, width: 1, height: 1 });
-
-    figma.notify('🔄 Loading pack...');
+    // Show the UI panel visibly with the loading view from the very start
+    // so progress messages render in-panel above the drop animation
+    // (handled by setStatus → postMessage). The UI also relays fetch
+    // requests since the code.js sandbox has no network access. Match the
+    // preflight panel size (520) so the panel doesn't resize-jump when
+    // the preflight view replaces the loading view, and so the drop's
+    // fall (translateY -300 from `bottom:58`) starts BELOW the status
+    // text instead of above it (which happened at height 400, where the
+    // drop's start anchored at the top of the panel).
+    figma.showUI(__html__, { width: 360, height: 520 });
+    figma.ui.postMessage({ type: 'show-view', view: 'loading' });
+    // Yield so the UI mounts and applies the loading view before the
+    // first setStatus message lands.
+    await new Promise(function (resolve) { setTimeout(resolve, 0); });
+
+    await setStatus('Reading your components…');
     const result = await refreshPack(GITHUB_CONFIG || undefined);
 
     if (!result.success || !result.pack) {
+      clearStatus();
       const message = getPackLoadErrorMessage(result.error);
       figma.notify('❌ ' + message);
       figma.showUI(__html__, { width: 360, height: 400 });
@@ -217,15 +442,36 @@ async function runGenerate(): Promise<void> {
     applyScannedTokens(result.pack.tokens);
     await saveAndBroadcastTokenSourceInfo(getTokenSourceInfoFromPack(result.pack));
 
+    // Empty-state guard: the dev server is reachable but the scan
+    // returned no usable components (no `.stories.tsx` / `.stories.ts`
+    // found under the configured paths). Stop here and show an
+    // actionable message instead of generating an empty page.
+    if (!COMPONENT_DEFS.components || COMPONENT_DEFS.components.length === 0) {
+      clearStatus();
+      figma.showUI(__html__, { width: 360, height: 400 });
+      figma.ui.postMessage({ type: 'show-view', view: 'offline' });
+      figma.ui.postMessage({
+        type: 'pack-load-error',
+        message:
+          'Connected to the dev server, but no Storybook stories were found. ' +
+          'Check `inkbridge.config.json:componentPaths`, or add `.stories.tsx` / ' +
+          '`.stories.ts` files next to your components. The `pnpm inkbridge:scan` ' +
+          'output names every file it inspected if you need details.',
+      });
+      shouldClose = false;
+      return;
+    }
+
+    await setStatus('Preparing fonts…');
     const failedFonts = await warmThemeFonts();
     if (failedFonts.length) {
       figma.notify(`⚠️ Font(s) not found in Figma: ${failedFonts.join(', ')}. Enable them via Figma's Google Fonts panel or install locally. Falling back to Inter.`, { timeout: 6000 });
     }
-    figma.notify('✅ Loaded ' + COMPONENT_DEFS.components.length + ' components');
 
     // Pre-fetch all image srcs found in component definitions
-    const imageSrcs = collectImageSrcs(COMPONENT_DEFS.components as any[]);
+    const imageSrcs = collectImageSrcs(COMPONENT_DEFS.components);
     if (imageSrcs.length > 0) {
+      await setStatus('Preloading images…');
       // Extract port from the source URL (e.g. 'http://localhost:3000/api/...')
       const portMatch = result.source?.match(/localhost:(\d+)/);
       const devPort = portMatch ? parseInt(portMatch[1], 10) : 3000;
@@ -237,14 +483,45 @@ async function runGenerate(): Promise<void> {
     rebuildColorIndex(TOKENS);
     createOrUpdateStyles();
 
-    // Single page build to avoid page-limit errors on free plans
-    buildDesignSystemSinglePage();
-    figma.notify('✅ Built Design System page (tokens + pack)');
-  } catch (e: any) {
-    figma.notify('❌ Failed: ' + e.message);
+    // Show preflight selection UI before generation
+    await setStatus('Detecting changes…');
+    const tokenHash = hashString(stableStringify(TOKENS));
+    const preflightItems = computePreflightData(tokenHash);
+    const excluded = await loadExcludedComponents();
+    // Prepend the design-tokens toggle. Compute its status against the
+    // existing tokens row's frame-hash so the preflight UI reflects
+    // reality: 'new' when the row doesn't exist (e.g. after Clean
+    // Generated Artifacts), 'changed' when token values shifted since
+    // the last build, 'unchanged' when nothing changed. Previously this
+    // was hardcoded to 'new' which made every fresh run show "design
+    // tokens changed" even when token values were identical.
+    let tokensStatus: 'new' | 'changed' | 'unchanged' = 'new';
+    const dsPage = figma.root && Array.isArray(figma.root.children)
+      ? figma.root.children.find(function (p) { return p.name === 'Design System' && p.type === 'PAGE'; })
+      : null;
+    if (dsPage) {
+      const existingTokensRow = findChildByName(dsPage, 'Design Tokens');
+      if (existingTokensRow) {
+        tokensStatus = getFrameHash(existingTokensRow) === tokenHash ? 'unchanged' : 'changed';
+      }
+    }
+    preflightItems.unshift({
+      name: DESIGN_TOKENS_TOGGLE,
+      displayName: 'Design tokens',
+      status: tokensStatus,
+      section: '__system__',
+      sectionTitle: 'Design system',
+    });
+    clearStatus();
+    figma.showUI(__html__, { visible: true, width: 360, height: 520 });
+    figma.ui.postMessage({ type: 'show-preflight', items: preflightItems, excluded: excluded });
+    shouldClose = false;
+  } catch (e) {
+    clearStatus();
+    figma.notify('❌ Failed: ' + errorMessage(e));
   } finally {
     if (shouldClose) {
-      await waitForAllFonts();
+      await waitForFontsBeforeClose();
       figma.closePlugin();
     }
   }
@@ -252,77 +529,6 @@ async function runGenerate(): Promise<void> {
 
 // ----------------------- Menu Command Handling -----------------------
 
-function debugSelection(): void {
-  const selection = figma.currentPage.selection || [];
-  if (selection.length === 0) {
-    figma.notify('No selection. Select a node and run Debug Selection.');
-    return;
-  }
-
-  const payload: any[] = [];
-  for (const node of selection) {
-    const entry: any = {
-      id: node.id,
-      name: node.name,
-      type: node.type,
-      width: (node as any).width,
-      height: (node as any).height,
-    };
-
-    if ('layoutMode' in node) {
-      entry.layoutMode = (node as any).layoutMode;
-      entry.layoutWrap = (node as any).layoutWrap;
-      entry.itemSpacing = (node as any).itemSpacing;
-      entry.counterAxisSpacing = (node as any).counterAxisSpacing;
-      entry.primaryAxisSizingMode = (node as any).primaryAxisSizingMode;
-      entry.counterAxisSizingMode = (node as any).counterAxisSizingMode;
-      entry.primaryAxisAlignItems = (node as any).primaryAxisAlignItems;
-      entry.counterAxisAlignItems = (node as any).counterAxisAlignItems;
-      entry.padding = {
-        top: (node as any).paddingTop,
-        right: (node as any).paddingRight,
-        bottom: (node as any).paddingBottom,
-        left: (node as any).paddingLeft,
-      };
-    }
-
-    if ('layoutAlign' in node) {
-      entry.layoutAlign = (node as any).layoutAlign;
-    }
-
-    if ('layoutGrow' in node) {
-      entry.layoutGrow = (node as any).layoutGrow;
-    }
-
-    if ('layoutPositioning' in node) {
-      entry.layoutPositioning = (node as any).layoutPositioning;
-    }
-
-    if ('children' in node) {
-      const childSummary: any[] = [];
-      const children = (node as any).children || [];
-      for (let i = 0; i < children.length; i++) {
-        const child = children[i];
-        childSummary.push({
-          name: child.name,
-          type: child.type,
-          width: child.width,
-          height: child.height,
-          layoutGrow: child.layoutGrow,
-          layoutAlign: child.layoutAlign,
-          layoutPositioning: child.layoutPositioning,
-        });
-      }
-      entry.children = childSummary;
-    }
-
-    payload.push(entry);
-  }
-
-  console.log('[TailwindTokens][DebugSelection]', payload);
-  figma.notify('Selection logged to console.');
-}
-
 async function handleCommand(command: string): Promise<void> {
   switch (command) {
     case 'push': {
@@ -367,8 +573,19 @@ async function handleCommand(command: string): Promise<void> {
       break;
     }
 
+    case 'clean-generated': {
+      const result = cleanGeneratedDesignSystemArtifacts();
+      if (result.removedNodes > 0) {
+        figma.notify('✅ Removed ' + result.removedNodes + ' generated node(s) across ' + result.touchedPages + ' page(s).');
+      } else {
+        figma.notify('No generated artifacts found.');
+      }
+      figma.closePlugin();
+      break;
+    }
+
     case 'debug-selection': {
-      debugSelection();
+      runDebugSelectionCommand();
       figma.closePlugin();
       break;
     }
@@ -382,7 +599,46 @@ async function handleCommand(command: string): Promise<void> {
 
 // ----------------------- UI Message Handler -----------------------
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- UI postMessage payloads are untyped JSON
 figma.ui.onmessage = async (msg: any) => {
+  if (msg.type === 'confirm-preflight') {
+    const excluded: string[] = Array.isArray(msg.excluded) ? msg.excluded as string[] : [];
+    await saveExcludedComponents(excluded);
+    // The UI is already visible (the preflight view sent this message), so
+    // just switch to the empty loading view rather than re-invoking
+    // `showUI` — reinvocation triggers an iframe rerender that leaves the
+    // window blank until the UI finishes reloading. The loading view is
+    // intentionally empty; only the bottom bridge watermark stays visible
+    // while the toast handles phase feedback.
+    figma.ui.postMessage({ type: 'show-view', view: 'loading' });
+    // Let the UI process the view-switch before we block the main thread
+    // with the synchronous build work.
+    await new Promise(function (resolve) { setTimeout(resolve, 0); });
+    try {
+      await buildDesignSystemSinglePage(excluded, { onStatus: setStatus });
+      clearStatus();
+      figma.notify('✅ Design system created');
+    } catch (e) {
+      clearStatus();
+      const message = errorMessage(e);
+      const stack = e instanceof Error && e.stack ? e.stack : '';
+      if (stack) {
+        console.error('[Inkbridge][BuildFailed]', stack);
+      } else {
+        console.error('[Inkbridge][BuildFailed]', message);
+      }
+      figma.notify('❌ Build failed: ' + message, { timeout: 10000 });
+    }
+    await waitForFontsBeforeClose();
+    figma.closePlugin();
+    return;
+  }
+
+  if (msg.type === 'cancel-preflight') {
+    figma.closePlugin();
+    return;
+  }
+
   // Handle UI iframe ready signal
   if (msg.type === 'ui-ready') {
     handleUIReady();
@@ -392,6 +648,7 @@ figma.ui.onmessage = async (msg: any) => {
   // Handle license validation result from UI iframe
   if (msg.type === 'license-result') {
     const tier: 'free' | 'pro' = msg.tier === 'pro' ? 'pro' : 'free';
+    sessionTier = tier;
     await figma.clientStorage.setAsync('license_tier', tier);
     await figma.clientStorage.setAsync('license_cache_at', String(Date.now()));
     if (pendingLicenseResolve) {
@@ -444,8 +701,8 @@ figma.ui.onmessage = async (msg: any) => {
       setTimeout(() => {
         figma.ui.postMessage({ type: 'show-view', view: 'overview' });
       }, 1000);
-    } catch (e: any) {
-      figma.ui.postMessage({ type: 'config-status', message: 'Failed to save token: ' + e.message, success: false });
+    } catch (e) {
+      figma.ui.postMessage({ type: 'config-status', message: 'Failed to save token: ' + errorMessage(e), success: false });
     }
   }
 
@@ -456,7 +713,7 @@ figma.ui.onmessage = async (msg: any) => {
         repo: msg.repo || '',
         baseBranch: msg.baseBranch || 'main',
         tokenPath: msg.tokenPath || 'design-tokens/tokens.dtcg.json',
-        tokenSourceMode: msg.tokenSourceMode || 'auto',
+        tokenSourceMode: msg.tokenSourceMode || 'css',
         cssTokenPath: msg.cssTokenPath || '',
         syncDtcgOnPush: msg.syncDtcgOnPush === true,
         allowNewTokensFromFigma: msg.allowNewTokensFromFigma === true,
@@ -486,22 +743,32 @@ figma.ui.onmessage = async (msg: any) => {
           figma.ui.postMessage({ type: 'show-view', view: 'overview' });
         }, 800);
       }
-    } catch (e: any) {
-      figma.ui.postMessage({ type: 'settings-status', message: 'Failed: ' + e.message, success: false });
+    } catch (e) {
+      figma.ui.postMessage({ type: 'settings-status', message: 'Failed: ' + errorMessage(e), success: false });
     }
   }
 
   if (msg.type === 'push-to-github') {
+    const pushTier = await checkLicense();
+    if (pushTier !== 'pro') {
+      figma.ui.postMessage({ type: 'show-view', view: 'upgrade' });
+      return;
+    }
     try {
       figma.ui.postMessage({ type: 'push-status', message: 'Creating branch...', success: null });
       const prUrl = await pushToGitHub(msg.commitMessage, msg.prDescription);
       figma.ui.postMessage({ type: 'push-status', message: 'PR created!', success: true, url: prUrl });
-    } catch (e: any) {
-      figma.ui.postMessage({ type: 'push-status', message: 'Failed: ' + e.message, success: false });
+    } catch (e) {
+      figma.ui.postMessage({ type: 'push-status', message: 'Failed: ' + errorMessage(e), success: false });
     }
   }
 
   if (msg.type === 'detect-changes') {
+    const detectTier = await checkLicense();
+    if (detectTier !== 'pro') {
+      figma.ui.postMessage({ type: 'show-view', view: 'upgrade' });
+      return;
+    }
     try {
       await loadConfig();
       const pushToken = await figma.clientStorage.getAsync('github_token') as string | null;
@@ -532,16 +799,16 @@ figma.ui.onmessage = async (msg: any) => {
 
       // Detect changes between Figma and code
       const changes = detectComponentChanges();
-      if ((changes as any).error) {
+      if (changes.error) {
         figma.showUI(__html__, { width: 360, height: 520 });
         figma.ui.postMessage({ type: 'show-view', view: 'sync' });
         figma.ui.postMessage({ type: 'config-loaded', config: GITHUB_CONFIG, hasToken: !!pushToken });
         await postTokenSourceInfoToUI();
         figma.ui.postMessage({ type: 'changes-detected', changes: { tokens: false, components: [] } });
-        figma.ui.postMessage({ type: 'sync-status', message: String((changes as any).error), success: false });
+        figma.ui.postMessage({ type: 'sync-status', message: String(changes.error), success: false });
         return;
       }
-      const componentChanges = Array.isArray((changes as any).changes) ? (changes as any).changes : [];
+      const componentChanges = Array.isArray(changes.changes) ? changes.changes : [];
       const tokenPreview = await previewTokenChanges(pushToken);
       const hasTokenChanges = tokenPreview.hasChanges;
 
@@ -565,14 +832,19 @@ figma.ui.onmessage = async (msg: any) => {
       figma.ui.postMessage({ type: 'config-loaded', config: GITHUB_CONFIG, hasToken: !!pushToken });
       await postTokenSourceInfoToUI();
       figma.ui.postMessage({ type: 'changes-detected', changes: { tokens: hasTokenChanges, components: componentChanges } });
-    } catch (e: any) {
+    } catch (e) {
       figma.showUI(__html__, { width: 360, height: 520 });
       figma.ui.postMessage({ type: 'show-view', view: 'sync' });
-      figma.ui.postMessage({ type: 'sync-status', message: 'Failed: ' + e.message, success: false });
+      figma.ui.postMessage({ type: 'sync-status', message: 'Failed: ' + errorMessage(e), success: false });
     }
   }
 
   if (msg.type === 'sync-to-github') {
+    const syncTier = await checkLicense();
+    if (syncTier !== 'pro') {
+      figma.ui.postMessage({ type: 'show-view', view: 'upgrade' });
+      return;
+    }
     try {
       figma.notify('Sync request received', { timeout: 1200 });
       figma.ui.postMessage({ type: 'sync-status', message: 'Starting sync...', success: null });
@@ -586,13 +858,18 @@ figma.ui.onmessage = async (msg: any) => {
         }
       );
       figma.ui.postMessage({ type: 'sync-status', message: 'PR created!', success: true, url: prUrl });
-    } catch (e: any) {
-      figma.notify('Sync failed: ' + e.message, { timeout: 2500 });
-      figma.ui.postMessage({ type: 'sync-status', message: 'Failed: ' + e.message, success: false });
+    } catch (e) {
+      figma.notify('Sync failed: ' + errorMessage(e), { timeout: 2500 });
+      figma.ui.postMessage({ type: 'sync-status', message: 'Failed: ' + errorMessage(e), success: false });
     }
   }
 
   if (msg.type === 'show-push') {
+    const showPushTier = await checkLicense();
+    if (showPushTier !== 'pro') {
+      figma.ui.postMessage({ type: 'show-view', view: 'upgrade' });
+      return;
+    }
     await loadConfig();
     const hasPushToken = await figma.clientStorage.getAsync('github_token');
     figma.ui.postMessage({ type: 'show-view', view: 'push' });
@@ -632,15 +909,20 @@ figma.ui.onmessage = async (msg: any) => {
     }
     rebuildColorIndex(TOKENS);
     createOrUpdateStyles();
-    buildDesignSystemSinglePage();
-    figma.notify('✅ Built Design System page');
-    await waitForAllFonts();
+    await buildDesignSystemSinglePage();
+    figma.notify('✅ Design system created');
+    await waitForFontsBeforeClose();
     figma.closePlugin();
   }
 
   if (msg.type === 'resize') {
     const h = typeof msg.height === 'number' ? Math.max(80, msg.height) : 400;
-    figma.ui.resize(320, h);
+    // Preserve the current panel width — different flows show the panel
+    // at different widths (320 for settings/configure, 360 for loading /
+    // preflight / sync). The UI passes its viewport width so we don't
+    // snap to a hardcoded value and cause a horizontal jump.
+    const w = typeof msg.width === 'number' ? Math.max(120, msg.width) : 320;
+    figma.ui.resize(w, h);
   }
 
   if (msg.type === 'show-settings') {
@@ -665,14 +947,14 @@ if (figma.codegen && typeof figma.codegen.on === 'function') {
   // Initialize color index for codegen
   rebuildColorIndex(TOKENS);
 
-  figma.codegen.on('generate', (event: any) => {
+  figma.codegen.on('generate', (event: { node: SceneNode }) => {
     try {
       const node = event.node;
       const classes = tailwindForNode(node);
       const code = 'className="' + classes + '"';
       return [{ title: 'Tailwind CSS', code, language: 'PLAINTEXT' }];
-    } catch (e: any) {
-      return [{ title: 'Tailwind CSS', code: '// Unable to generate: ' + e.message, language: 'PLAINTEXT' }];
+    } catch (e) {
+      return [{ title: 'Tailwind CSS', code: '// Unable to generate: ' + errorMessage(e), language: 'PLAINTEXT' }];
     }
   });
 }