inkbridge 0.1.0-beta.21 → 0.1.0-beta.23

package/src/tokens/variables.ts

@@ -1,4 +1,25 @@
-import { TOKENS } from './tokens';
+import { TOKENS, extractFontName, isConsumerOwnedToken } from './tokens';
+
+/**
+ * Filter an entry map down to the consumer-owned keys for a given
+ * theme/group. Used by every demoFrame* to drop Tailwind defaults that
+ * leaked in through `@import "tailwindcss"` (e.g. `serif: Cambria`,
+ * `spacing.base: 0.25rem`, the full breakpoint scale). When no
+ * consumer-only scan is available (pre-scan, embedded fallback, older
+ * CLI output), `isConsumerOwnedToken` returns true for all keys —
+ * preserves the pre-Concern-#2 behaviour as a graceful fallback.
+ */
+function filterConsumerOwned(
+  theme: string,
+  group: string,
+  entries: Record<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const key of Object.keys(entries)) {
+    if (isConsumerOwnedToken(theme, group, key)) out[key] = entries[key];
+  }
+  return out;
+}
 import { parseColor, colorToLabel, debug, normalizeThemeName, normalizeGroupName, normalizeSizeValue } from './colors';
 
 // ---------------------------------------------------------------------------
@@ -902,6 +923,68 @@ export function createOrUpdateStylesFallback(): void {
 /**
  * Bind a frame's fill to a color variable (semantic token).
  */
+/**
+ * Universal color application for any token slot — `fill` or `stroke`,
+ * for any node that has the corresponding property (frames, text). Tries
+ * variable binding first (so the result tracks theme mode changes), then
+ * falls back to a raw color value.
+ *
+ * Single source of truth that collapses the previously-duplicated bg-apply
+ * and border-apply blocks in tailwind.ts, cva-master.ts, and
+ * component-gen.ts. Adding a new color slot (e.g. focus-ring overlay,
+ * decorative SVG fill) becomes a one-liner against this helper instead of
+ * another copy-pasted variable-binding block.
+ *
+ * Returns `true` when EITHER the variable bound OR the literal color was
+ * applied — callers that need to schedule side effects (e.g. `strokeWeight
+ * = 1` only when a stroke was actually painted) gate on the return value.
+ */
+export function applyTokenColor(
+  node: SceneNode,
+  slot: 'fill' | 'stroke',
+  intent: { token?: string | null; value?: string | null; opacity?: number | null },
+  theme?: string,
+): boolean {
+  // Figma's plugin API silently normalises a bound paint's `opacity` to 1
+  // on `node.fills = […]` reassignment when `boundVariables.color` is set.
+  // No combination of bake-before-bind, bake-after-bind, or Object.assign
+  // clones survives that normalisation (verified with traces of
+  // inputOpacity 0.6 → storedOpacity 1 on every variant). The only path
+  // that preserves partial alpha is to skip variable binding entirely and
+  // write a literal SOLID paint with `opacity` set. Trade-off: a theme /
+  // mode switch won't re-resolve the color for that fill. Acceptable
+  // because the consumer's `/N` modifier on the class was a compile-time
+  // decision in CSS too — Tailwind bakes the alpha at build time, not at
+  // theme-switch time.
+  const wantsPartialAlpha = intent.opacity != null && intent.opacity < 1;
+  if (intent.token && !wantsPartialAlpha) {
+    if (bindColorVariable(node, intent.token, slot, theme)) return true;
+  }
+  if (!intent.value) return false;
+  const color = parseColor(intent.value);
+  const opacity = intent.opacity != null
+    ? Math.max(0, Math.min(1, intent.opacity))
+    : (color.a == null ? 1 : color.a);
+  const paint: SolidPaint = {
+    type: 'SOLID',
+    color: { r: color.r, g: color.g, b: color.b },
+    opacity,
+  };
+  try {
+    if (slot === 'fill' && 'fills' in node) {
+      node.fills = [paint];
+      return true;
+    }
+    if (slot === 'stroke' && 'strokes' in node) {
+      node.strokes = [paint];
+      return true;
+    }
+  } catch (_err) {
+    // Some node types reject the assignment; bail silently.
+  }
+  return false;
+}
+
 export function bindColorVariable(node: SceneNode, tokenKey: string, fillOrStroke: string, theme?: string): boolean {
   const resolvedTheme =
     (theme && (_themeColorVariables[theme] || _variableModeIds[theme])) ? theme :
@@ -914,20 +997,20 @@ export function bindColorVariable(node: SceneNode, tokenKey: string, fillOrStrok
   if (!variable) return false;
 
   try {
+    // Bound paints render at opacity 1 always — Figma's plugin API
+    // silently normalises a bound paint's `opacity` to 1 on `node.fills
+    // = [paint]` reassignment regardless of what the input paint
+    // carried. Callers that need partial alpha must skip binding and
+    // use a literal SOLID paint instead (see `applyTokenColor`'s
+    // `wantsPartialAlpha` short-circuit).
     if (fillOrStroke === 'fill' && 'fills' in node) {
-      const fills: Paint[] = JSON.parse(JSON.stringify(node.fills || []));
-      if (fills.length === 0) {
-        fills.push({ type: 'SOLID', color: { r: 1, g: 1, b: 1 }, opacity: 1 });
-      }
-      fills[0] = figma.variables.setBoundVariableForPaint(fills[0] as SolidPaint, 'color', variable);
-      node.fills = fills;
+      const seed: SolidPaint = { type: 'SOLID', color: { r: 1, g: 1, b: 1 } };
+      const bound = figma.variables.setBoundVariableForPaint(seed, 'color', variable);
+      node.fills = [bound];
     } else if (fillOrStroke === 'stroke' && 'strokes' in node) {
-      const strokes: Paint[] = JSON.parse(JSON.stringify(node.strokes || []));
-      if (strokes.length === 0) {
-        strokes.push({ type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } });
-      }
-      strokes[0] = figma.variables.setBoundVariableForPaint(strokes[0] as SolidPaint, 'color', variable);
-      node.strokes = strokes;
+      const seed: SolidPaint = { type: 'SOLID', color: { r: 0.9, g: 0.9, b: 0.9 } };
+      const bound = figma.variables.setBoundVariableForPaint(seed, 'color', variable);
+      node.strokes = [bound];
     }
     return true;
   } catch (e) {
@@ -1135,11 +1218,58 @@ function makeSectionFrame(name: string): FrameNode {
   return frame;
 }
 
+// Column layout for the color demo grid:
+//   * Up to MAX_COLOR_COLUMNS columns side-by-side.
+//   * Minimum COLOR_MIN_ROWS_PER_COLUMN rows per column so small themes
+//     don't render as a row of tiny single-entry columns.
+//   * Once the column cap is hit, additional entries extend the per-column
+//     height instead of opening a 4th column — keeps the grid visually
+//     bounded on the Design System page.
+//
+// Effective rows-per-column = max(MIN, ceil(entries / MAX_COLUMNS)). So:
+//   12 entries → 1 column ×12 rows   (under MIN, single column)
+//   30 entries → 2 columns ×15 rows   (rounded up to MIN)
+//   45 entries → 3 columns ×15 rows
+//   60 entries → 3 columns ×20 rows   (column cap holds, rows grow)
+const MAX_COLOR_COLUMNS = 3;
+const COLOR_MIN_ROWS_PER_COLUMN = 15;
+
 export function demoFrameColors(theme: string): FrameNode {
   const frame = makeSectionFrame(theme.toUpperCase() + ' Colors');
   frame.appendChild(makeSectionTitle(getThemeDisplayName(theme)));
-  const col: Record<string, string> = getThemeGroup(theme, 'color');
-  for (const [key, val] of Object.entries(col)) {
+
+  // Inner horizontal grid: one VERTICAL column per slice of
+  // rowsPerColumn entries. Outer section frame stays VERTICAL so
+  // the title remains above the column row.
+  const grid = figma.createFrame();
+  grid.name = 'color-grid';
+  grid.layoutMode = 'HORIZONTAL';
+  grid.primaryAxisSizingMode = 'AUTO';
+  grid.counterAxisSizingMode = 'AUTO';
+  grid.itemSpacing = 32;
+  grid.counterAxisAlignItems = 'MIN';
+  grid.fills = [];
+  grid.strokes = [];
+
+  const entries = Object.entries(filterConsumerOwned(theme, 'color', getThemeGroup(theme, 'color')));
+  const rowsPerColumn = Math.max(
+    COLOR_MIN_ROWS_PER_COLUMN,
+    Math.ceil(entries.length / MAX_COLOR_COLUMNS),
+  );
+  let column: FrameNode | null = null;
+  for (let i = 0; i < entries.length; i++) {
+    if (i % rowsPerColumn === 0) {
+      column = figma.createFrame();
+      column.name = 'color-column-' + Math.floor(i / rowsPerColumn);
+      column.layoutMode = 'VERTICAL';
+      column.primaryAxisSizingMode = 'AUTO';
+      column.counterAxisSizingMode = 'AUTO';
+      column.itemSpacing = 12;
+      column.fills = [];
+      column.strokes = [];
+      grid.appendChild(column);
+    }
+    const [key, val] = entries[i];
     const row = figma.createFrame();
     row.layoutMode = 'HORIZONTAL';
     row.primaryAxisSizingMode = 'AUTO';
@@ -1157,12 +1287,19 @@ export function demoFrameColors(theme: string): FrameNode {
     const label = makeBodyText(key + ' \u2014 ' + colorToLabel(val));
     row.appendChild(swatch);
     row.appendChild(label);
-    frame.appendChild(row);
+    column!.appendChild(row);
   }
+
+  frame.appendChild(grid);
   return frame;
 }
 
-export function demoFrameRadii(): FrameNode {
+export function demoFrameRadii(): FrameNode | null {
+  const r: Record<string, string> = filterConsumerOwned(_defaultThemeName, 'radius', getThemeGroup(_defaultThemeName, 'radius'));
+  // Nothing the consumer wrote → hide the section entirely so the
+  // panel doesn't display an empty "Radii" placeholder.
+  if (Object.keys(r).length === 0) return null;
+
   const frame = makeSectionFrame('Radii');
 
   const row = figma.createFrame();
@@ -1172,8 +1309,6 @@ export function demoFrameRadii(): FrameNode {
   row.itemSpacing = 16;
   row.fills = [];
   row.strokes = [];
-
-  const r: Record<string, string> = getThemeGroup(_defaultThemeName, 'radius');
   for (const k of Object.keys(r)) {
     const cell = figma.createFrame();
     cell.layoutMode = 'VERTICAL';
@@ -1200,7 +1335,7 @@ export function demoFrameRadii(): FrameNode {
 }
 
 export function demoFrameFonts(theme: string): FrameNode | null {
-  const fonts: Record<string, string> = getThemeGroup(theme, 'font');
+  const fonts: Record<string, string> = filterConsumerOwned(theme, 'font', getThemeGroup(theme, 'font'));
   const keys = Object.keys(fonts);
   if (keys.length === 0) return null;
 
@@ -1208,22 +1343,13 @@ export function demoFrameFonts(theme: string): FrameNode | null {
   frame.appendChild(makeSectionTitle(getThemeDisplayName(theme)));
 
   for (const key of keys) {
-    const family = (function () {
-      const raw = String(fonts[key] || '');
-      const parts = raw.split(',');
-      for (const part of parts) {
-        const trimmed = part.trim();
-        const varMatch = trimmed.match(/^var\(--font-([a-z0-9-]+)\)/i);
-        if (varMatch) {
-          return varMatch[1].split('-').map((w: string) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
-        }
-        const lower = trimmed.toLowerCase().replace(/^["']|["']$/g, '');
-        if (lower === 'ui-sans-serif' || lower === 'system-ui' || lower === 'sans-serif' || lower === 'serif' || lower === 'monospace' || lower === 'ui-monospace') continue;
-        const cleaned = trimmed.replace(/^["']|["']$/g, '');
-        if (cleaned) return cleaned;
-      }
-      return 'Inter';
-    })();
+    // Use the shared extractor so this preview agrees with the actual
+    // rendering pipeline (`getThemeFontFamily` + render-time
+    // `setRangeFontName`). The previous inline extractor only filtered
+    // 6 keywords, missing `ui-serif`, `SFMono-Regular`, `Apple Color
+    // Emoji`, `Menlo`, etc. — so the preview rendered "SFMono-Regular"
+    // labels that Figma can't load (falling back to Inter visually).
+    const family = extractFontName(fonts[key]) || 'Inter';
 
     const cell = figma.createFrame();
     cell.layoutMode = 'VERTICAL';
@@ -1242,7 +1368,7 @@ export function demoFrameFonts(theme: string): FrameNode | null {
 }
 
 export function demoFrameSpacing(): FrameNode | null {
-  const spacing: Record<string, string> = getThemeGroup(_defaultThemeName, 'spacing');
+  const spacing: Record<string, string> = filterConsumerOwned(_defaultThemeName, 'spacing', getThemeGroup(_defaultThemeName, 'spacing'));
   const keys = Object.keys(spacing);
   if (keys.length === 0) return null;
 
@@ -1273,21 +1399,40 @@ export function demoFrameSpacing(): FrameNode | null {
 }
 
 export function demoFrameFontSizes(): FrameNode | null {
-  const sizes: Record<string, string> = getThemeGroup(_defaultThemeName, 'fontSize');
+  const sizes: Record<string, string> = filterConsumerOwned(_defaultThemeName, 'fontSize', getThemeGroup(_defaultThemeName, 'fontSize'));
   const keys = Object.keys(sizes);
   if (keys.length === 0) return null;
 
   const frame = makeSectionFrame('Font sizes');
 
+  // Inner wrapping row so large tokens (3xl, 9xl, …) lay out horizontally
+  // and roll to a new line when they overflow, instead of stacking into a
+  // tall single column. Label text is just the token key (`9xl`) rendered
+  // at its actual size — the visual IS the size, no need for a "—128px
+  // sample" annotation.
+  const row = figma.createFrame();
+  row.name = 'fontsize-row';
+  row.layoutMode = 'HORIZONTAL';
+  row.layoutWrap = 'WRAP';
+  row.primaryAxisSizingMode = 'FIXED';
+  row.counterAxisSizingMode = 'AUTO';
+  row.resize(720, row.height);
+  row.itemSpacing = 32;
+  row.counterAxisSpacing = 16;
+  row.counterAxisAlignItems = 'MIN';
+  row.fills = [];
+  row.strokes = [];
+
   for (const k of keys) {
     const px = pxFromSizeToken(sizes[k]);
-    frame.appendChild(makeBodyText(k + ' \u2014 ' + Math.round(px) + 'px sample', { size: px }));
+    row.appendChild(makeBodyText(k, { size: px }));
   }
+  frame.appendChild(row);
   return frame;
 }
 
 export function demoFrameBreakpoints(): FrameNode | null {
-  const breakpoints: Record<string, string> = getThemeGroup(_defaultThemeName, 'breakpoint');
+  const breakpoints: Record<string, string> = filterConsumerOwned(_defaultThemeName, 'breakpoint', getThemeGroup(_defaultThemeName, 'breakpoint'));
   const keys = Object.keys(breakpoints);
   if (keys.length === 0) return null;
 
@@ -1334,19 +1479,30 @@ export function demoFrameBreakpoints(): FrameNode | null {
 const SHADOW_SIZE_ORDER = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'];
 
 export function demoFrameShadows(theme: string): FrameNode | null {
-  const shadows: Record<string, string> = getThemeGroup(theme, 'shadow');
+  const shadows: Record<string, string> = filterConsumerOwned(theme, 'shadow', getThemeGroup(theme, 'shadow'));
   const ordered = SHADOW_SIZE_ORDER.filter((k) => shadows[k]);
   if (ordered.length === 0) return null;
 
   const frame = makeSectionFrame(theme.toUpperCase() + ' Shadows');
-  // Larger gap so big shadows (shadow-xl, shadow-2xl) don't visually overlap
-  // the next swatch — the default itemSpacing is too tight for shadow-2xl
-  // which extends ~38px below its rect.
-  frame.itemSpacing = 56;
   // Keep shadows from being clipped by the wrapper's bounds.
   frame.clipsContent = false;
   frame.appendChild(makeSectionTitle(getThemeDisplayName(theme)));
 
+  // Inner horizontal row so swatches read left-to-right under the title.
+  // The outer section frame stays VERTICAL so the title sits above. Larger
+  // itemSpacing here so big shadows (shadow-xl, shadow-2xl) don't visually
+  // overlap their neighbour — defaults are too tight for shadow-2xl which
+  // extends ~38px past its rect.
+  const row = figma.createFrame();
+  row.name = 'shadow-row';
+  row.layoutMode = 'HORIZONTAL';
+  row.primaryAxisSizingMode = 'AUTO';
+  row.counterAxisSizingMode = 'AUTO';
+  row.itemSpacing = 56;
+  row.fills = [];
+  row.strokes = [];
+  row.clipsContent = false;
+
   for (const k of ordered) {
     const cell = figma.createFrame();
     cell.layoutMode = 'VERTICAL';
@@ -1381,7 +1537,8 @@ export function demoFrameShadows(theme: string): FrameNode | null {
 
     cell.appendChild(swatch);
     cell.appendChild(makeBodyText(k, { size: 12 }));
-    frame.appendChild(cell);
+    row.appendChild(cell);
   }
+  frame.appendChild(row);
   return frame;
 }

package/templates/scan-components-route.ts

@@ -59,6 +59,14 @@ export async function GET(request: Request): Promise<NextResponse> {
     if (dtcgTokenPath) args.push('--dtcg-token-path', dtcgTokenPath);
 
     const result = spawnSync(TSX, args, { cwd: CWD, encoding: 'utf-8' });
+    // Forward captured subprocess streams to the dev server's terminal.
+    // `spawnSync` with `encoding` captures stdout/stderr into the result
+    // object instead of inheriting them, so any `console.log` /
+    // `console.error` inside the scanner would otherwise be invisible.
+    // Reprinting here means scanner diagnostics surface in the same place
+    // as Next.js logs — no per-debug-session instrumentation needed.
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
     if (result.status !== 0) {
       throw new Error(result.stderr || 'Scanner exited with non-zero status');
     }

package/ui.html

@@ -91,6 +91,48 @@
       letter-spacing: 0.5px;
     }
 
+    /* Advanced disclosure — `<details>`-based collapsible section.
+       Keeps DTCG-mode + sync knobs out of sight for CSS-first users
+       (the majority) but one click away when needed. */
+    .advanced-details {
+      margin: 0;
+    }
+    .advanced-details > summary {
+      cursor: pointer;
+      list-style: none;
+      font-size: 11px;
+      font-weight: 600;
+      color: #333;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      padding: 0;
+      margin-bottom: 12px;
+      user-select: none;
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+    .advanced-details > summary::-webkit-details-marker { display: none; }
+    .advanced-details > summary::before {
+      content: '▸';
+      font-size: 10px;
+      color: #666;
+      transition: transform 0.15s ease;
+      display: inline-block;
+      width: 8px;
+      text-align: center;
+    }
+    .advanced-details[open] > summary::before {
+      transform: rotate(90deg);
+    }
+    .advanced-details > summary > .summary-hint {
+      font-weight: 400;
+      font-size: 10px;
+      color: #888;
+      text-transform: none;
+      letter-spacing: 0;
+    }
+
     .repo-display {
       font-size: 11px;
       color: #666;
@@ -439,48 +481,54 @@
       <input type="text" id="settingsBranch" placeholder="main" value="main">
     </div>
 
-    <div class="field">
-      <label>Token Source Mode</label>
-      <select id="settingsTokenSourceMode">
-        <option value="css">css (auto-discover CSS, fallback to DTCG)</option>
-        <option value="dtcg">dtcg (force DTCG file only)</option>
-      </select>
-      <p class="hint">CSS mode auto-discovers your globals.css and falls back to DTCG if not found. Use DTCG to force the legacy token file.</p>
-    </div>
+    <div class="divider"></div>
 
-    <div class="field" id="tokenPathField">
-      <label>DTCG Token Path</label>
-      <input type="text" id="settingsTokenPath" placeholder="design-tokens/tokens.dtcg.json" value="design-tokens/tokens.dtcg.json">
-      <p class="hint">Path to the DTCG token file (used in dtcg mode or as fallback in auto mode)</p>
-    </div>
+    <details class="advanced-details" id="advancedTokenDetails">
+      <summary>Advanced — Token Sync <span class="summary-hint">(DTCG, push policy)</span></summary>
 
-    <div class="field" id="cssTokenPathField">
-      <label>CSS Token Path (optional)</label>
-      <input type="text" id="settingsCssTokenPath" placeholder="src/app/tokens.css">
-      <p class="hint">Overrides CSS auto-discovery when set.</p>
-    </div>
+      <div class="field">
+        <label>Token Source Mode</label>
+        <select id="settingsTokenSourceMode">
+          <option value="css">css (recommended — auto-discover globals.css)</option>
+          <option value="dtcg">dtcg (force DTCG file — Tokens Studio / Style Dictionary)</option>
+        </select>
+        <p class="hint">Most projects use CSS-first tokens (custom properties in <code>globals.css</code> or imported tokens.css). Pick <code>dtcg</code> only if your source of truth is a <code>tokens.dtcg.json</code> file.</p>
+      </div>
 
-    <div class="field" id="syncDtcgOnPushField">
-      <div style="display:flex;align-items:center;gap:8px;">
-        <input type="checkbox" id="settingsSyncDtcgOnPush" style="width:auto;flex-shrink:0;">
-        <label for="settingsSyncDtcgOnPush" style="display:inline;margin:0;cursor:pointer;">Also update DTCG on Push to Code</label>
+      <div class="field" id="cssTokenPathField">
+        <label>CSS Token Path (optional)</label>
+        <input type="text" id="settingsCssTokenPath" placeholder="src/app/tokens.css">
+        <p class="hint">Overrides CSS auto-discovery when set. Leave blank unless your tokens live outside <code>globals.css</code> and aren't imported from it.</p>
       </div>
-      <p class="hint">When enabled, the plugin also commits <code>tokens.dtcg.json</code> as a generated artifact.</p>
-    </div>
 
-    <div class="field">
-      <div style="display:flex;align-items:center;gap:8px;">
-        <input type="checkbox" id="settingsAllowNewTokensFromFigma" style="width:auto;flex-shrink:0;">
-        <label for="settingsAllowNewTokensFromFigma" style="display:inline;margin:0;cursor:pointer;">Allow New Tokens from Figma</label>
+      <div class="field" id="tokenPathField">
+        <label>DTCG Token Path</label>
+        <input type="text" id="settingsTokenPath" placeholder="design-tokens/tokens.dtcg.json">
+        <p class="hint">Path to the DTCG token file (used in dtcg mode or as fallback in css mode when no CSS file is found). Leave blank for the default <code>design-tokens/tokens.dtcg.json</code>.</p>
       </div>
-      <p class="hint">Disabled by default. When enabled, new token keys can be added to code on push.</p>
-    </div>
 
-    <div class="field" id="newTokenPrefixesField" style="display:none;">
-      <label>New Token Prefixes (optional)</label>
-      <input type="text" id="settingsNewTokenPrefixes" placeholder="chart-, brand-">
-      <p class="hint">Comma-separated. Only tokens with these prefixes can be added. Leave empty to allow all new tokens.</p>
-    </div>
+      <div class="field" id="syncDtcgOnPushField">
+        <div style="display:flex;align-items:center;gap:8px;">
+          <input type="checkbox" id="settingsSyncDtcgOnPush" style="width:auto;flex-shrink:0;">
+          <label for="settingsSyncDtcgOnPush" style="display:inline;margin:0;cursor:pointer;">Also update DTCG on Push to Code</label>
+        </div>
+        <p class="hint">When enabled, the plugin also commits <code>tokens.dtcg.json</code> as a generated artifact alongside the CSS file.</p>
+      </div>
+
+      <div class="field">
+        <div style="display:flex;align-items:center;gap:8px;">
+          <input type="checkbox" id="settingsAllowNewTokensFromFigma" style="width:auto;flex-shrink:0;">
+          <label for="settingsAllowNewTokensFromFigma" style="display:inline;margin:0;cursor:pointer;">Allow New Tokens from Figma</label>
+        </div>
+        <p class="hint">Disabled by default. When enabled, new token keys can be added to code on push.</p>
+      </div>
+
+      <div class="field" id="newTokenPrefixesField" style="display:none;">
+        <label>New Token Prefixes (optional)</label>
+        <input type="text" id="settingsNewTokenPrefixes" placeholder="chart-, brand-">
+        <p class="hint">Comma-separated. Only tokens with these prefixes can be added. Leave empty to allow all new tokens.</p>
+      </div>
+    </details>
 
     <div class="divider"></div>
 
@@ -497,6 +545,16 @@
 
     <div class="divider"></div>
 
+    <div class="section-title">Dev Server (Optional)</div>
+
+    <div class="field">
+      <label>Dev Server Port</label>
+      <input type="text" id="settingsDevServerPort" placeholder="e.g., 3000" inputmode="numeric" maxlength="5">
+      <p class="hint">Pin the scanner to one localhost port. Leave blank to auto-discover across 3000 / 4000 / 5173. Useful when you're running multiple local projects on different ports.</p>
+    </div>
+
+    <div class="divider"></div>
+
     <div class="section-title">Display (Optional)</div>
 
     <div class="field">
@@ -769,8 +827,14 @@
     var newTokenPrefixesField = document.getElementById('newTokenPrefixesField');
     var settingsToken = document.getElementById('settingsToken');
     var settingsProjectName = document.getElementById('settingsProjectName');
+    var settingsDevServerPort = document.getElementById('settingsDevServerPort');
     var settingsLicenseKey = document.getElementById('settingsLicenseKey');
 
+    // Cached configured dev-server port — empty string means "auto-discover".
+    // Updated on `config-loaded` and at save time so the port override takes
+    // effect for subsequent fetches without requiring a plugin reload.
+    var configuredDevServerPort = '';
+
     // Current detected changes
     var detectedChanges = { tokens: true, components: [] };
     var lastTokenSourceInfo = null;
@@ -1092,17 +1156,35 @@
 
     // Dev server fetch - runs in the UI iframe which has network access
     // (code.js sandbox cannot make fetch calls)
-    var DEV_SERVER_ENDPOINTS = [
-      'http://localhost:3000/api/inkbridge/scan-components',
-      'http://localhost:4000/api/inkbridge/scan-components',
-      'http://localhost:5173/api/inkbridge/scan-components',
-    ];
+    var DEFAULT_DEV_SERVER_PORTS = [3000, 4000, 5173];
+
+    // Resolve the dev-server ports to try. A configured `devServerPort`
+    // (validated to 1-65535 by the config normaliser) collapses the
+    // sweep to that single port — useful when the user has multiple
+    // local projects on different ports.
+    function getDevServerPorts() {
+      var raw = (configuredDevServerPort || '').trim();
+      if (!raw) return DEFAULT_DEV_SERVER_PORTS;
+      var n = parseInt(raw, 10);
+      if (!isFinite(n) || n < 1 || n > 65535) return DEFAULT_DEV_SERVER_PORTS;
+      return [n];
+    }
+
+    function getScanComponentsEndpoints() {
+      var ports = getDevServerPorts();
+      var out = [];
+      for (var i = 0; i < ports.length; i++) {
+        out.push('http://localhost:' + ports[i] + '/api/inkbridge/scan-components');
+      }
+      return out;
+    }
 
     var DEV_SERVER_TIMEOUT_MS = 15000;
 
     async function fetchComponentDefs() {
-      for (var i = 0; i < DEV_SERVER_ENDPOINTS.length; i++) {
-        var url = DEV_SERVER_ENDPOINTS[i];
+      var endpoints = getScanComponentsEndpoints();
+      for (var i = 0; i < endpoints.length; i++) {
+        var url = endpoints[i];
         try {
           var controller = new AbortController();
           var timeoutId = setTimeout(function() { controller.abort(); }, DEV_SERVER_TIMEOUT_MS);
@@ -1255,7 +1337,7 @@
       // UI-side license validation (code.js sandbox has no network)
       if (msg.type === 'validate-license') {
         var licenseResult = { tier: 'free', valid: false };
-        var validatePorts = ['3000', '4000', '5173'];
+        var validatePorts = getDevServerPorts();
         for (var vp = 0; vp < validatePorts.length; vp++) {
           try {
             var vUrl = 'http://localhost:' + validatePorts[vp] + '/api/plugin/validate?key=' + encodeURIComponent(msg.key);
@@ -1426,10 +1508,25 @@
         settingsNewTokenPrefixes.value = Array.isArray(config.newTokenPrefixes) ? config.newTokenPrefixes.join(', ') : (typeof config.newTokenPrefixes === 'string' ? config.newTokenPrefixes : '');
         newTokenPrefixesField.style.display = config.allowNewTokensFromFigma === true ? 'block' : 'none';
         settingsProjectName.value = config.projectName || '';
+        settingsDevServerPort.value = config.devServerPort || '';
+        configuredDevServerPort = (config.devServerPort || '').trim();
         configuredTokenSourceMode = tokenSourceMode;
         applyTokenSourceModeVisibility(tokenSourceMode);
         setTokenSourceInfo(lastTokenSourceInfo);
 
+        // Auto-expand the Advanced disclosure when the consumer has any
+        // non-default token-sync setting. Default state (css mode, no
+        // overrides, no DTCG sync, default new-token policy) stays
+        // collapsed — clean form for the CSS-first majority.
+        var advancedHasNonDefault =
+          tokenSourceMode !== 'css'
+          || (config.tokenPath && config.tokenPath !== 'design-tokens/tokens.dtcg.json')
+          || (config.cssTokenPath && config.cssTokenPath.length > 0)
+          || config.syncDtcgOnPush === true
+          || config.allowNewTokensFromFigma === true;
+        var advancedTokenDetails = document.getElementById('advancedTokenDetails');
+        if (advancedTokenDetails) advancedTokenDetails.open = advancedHasNonDefault;
+
         // Update push view repo info
         if (config.owner && config.repo) {
           repoLabel.textContent = config.owner + '/' + config.repo;
@@ -1650,10 +1747,14 @@
             .map(function(v) { return v.trim(); })
             .filter(function(v) { return v.length > 0; }),
           projectName: settingsProjectName.value.trim(),
+          devServerPort: settingsDevServerPort.value.trim(),
           token: settingsToken.value.trim() || null,
           licenseKey: settingsLicenseKey.value.trim() || null
         }
       }, '*');
+      // Keep the in-page port cache in sync so subsequent dev-server
+      // fetches respect the new value without waiting for a reload.
+      configuredDevServerPort = settingsDevServerPort.value.trim();
     };
 
     settingsTokenSourceMode.onchange = function() {