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

package/src/effects/icon-builder.ts

@@ -0,0 +1,1074 @@
+/**
+ * Icon Builder Module
+ *
+ * Handles icon creation, SVG processing, and icon manipulation for Figma.
+ * Extracted from ui-builder.ts for better modularity.
+ */
+
+import { COMPONENT_DEFS } from '../tokens';
+import type { RGB } from '../tokens/colors';
+import type { NodeIR } from '../tailwind/node-ir';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const ICON_PATHS: Record<string, { d: string; viewBox: number; stroke: boolean; strokeWidth?: number }> = {
+  home: {
+    d: "M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6",
+    viewBox: 24,
+    stroke: true,
+    strokeWidth: 2
+  },
+  portfolio: {
+    d: "M3 3C2.44772 3 2 3.44772 2 4V20C2 20.5523 2.44772 21 3 21H21C21.5523 21 22 20.5523 22 20V4C22 3.44772 21.5523 3 21 3H3ZM8 5V8H4V5H8ZM4 14V10H8V14H4ZM4 16H8V19H4V16ZM10 16H20V19H10V16ZM20 14H10V10H20V14ZM20 5V8H10V5H20Z",
+    viewBox: 24,
+    stroke: false
+  },
+  strategy: {
+    d: "M12 22C6.477 22 2 17.523 2 12S6.477 2 12 2s10 4.477 10 10-4.477 10-10 10Z M16.5 7.5 14 14 7.5 16.5 10 10l6.5-2.5Zm-4.5 5.5a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z",
+    viewBox: 24,
+    stroke: true,
+    strokeWidth: 1.8
+  },
+  pda: {
+    d: "M22.0049 7.99979H13.0049C12.4526 7.99979 12.0049 8.4475 12.0049 8.99979V14.9998C12.0049 15.5521 12.4526 15.9998 13.0049 15.9998H22.0049V19.9998C22.0049 20.5521 21.5572 20.9998 21.0049 20.9998H3.00488C2.4526 20.9998 2.00488 20.5521 2.00488 19.9998V3.99979C2.00488 3.4475 2.4526 2.99979 3.00488 2.99979H21.0049C21.5572 2.99979 22.0049 3.4475 22.0049 3.99979V7.99979ZM15.0049 10.9998H18.0049V12.9998H15.0049V10.9998Z",
+    viewBox: 24,
+    stroke: false
+  },
+  account: {
+    d: "M3 4.99509C3 3.89323 3.89262 3 4.99509 3H19.0049C20.1068 3 21 3.89262 21 4.99509V19.0049C21 20.1068 20.1074 21 19.0049 21H4.99509C3.89323 21 3 20.1074 3 19.0049V4.99509ZM5 5V19H19V5H5ZM7.97216 18.1808C7.35347 17.9129 6.76719 17.5843 6.22083 17.2024C7.46773 15.2753 9.63602 14 12.1022 14C14.5015 14 16.6189 15.2071 17.8801 17.0472C17.3438 17.4436 16.7664 17.7877 16.1555 18.0718C15.2472 16.8166 13.77 16 12.1022 16C10.3865 16 8.87271 16.8641 7.97216 18.1808ZM12 13C10.067 13 8.5 11.433 8.5 9.5C8.5 7.567 10.067 6 12 6C13.933 6 15.5 7.567 15.5 9.5C15.5 11.433 13.933 13 12 13ZM12 11C12.8284 11 13.5 10.3284 13.5 9.5C13.5 8.67157 12.8284 8 12 8C11.1716 8 10.5 8.67157 10.5 9.5C10.5 10.3284 11.1716 11 12 11Z",
+    viewBox: 24,
+    stroke: false
+  },
+  logout: {
+    d: "M3 3a1 1 0 00-1 1v12a1 1 0 102 0V4a1 1 0 00-1-1zm10.293 9.293a1 1 0 001.414 1.414l3-3a1 1 0 000-1.414l-3-3a1 1 0 10-1.414 1.414L14.586 9H7a1 1 0 100 2h7.586l-1.293 1.293z",
+    viewBox: 20,
+    stroke: false
+  },
+  menu: {
+    d: "M4 6h16M4 12h16M4 18h16",
+    viewBox: 24,
+    stroke: true,
+    strokeWidth: 2
+  },
+  close: {
+    d: "M6 18L18 6M6 6l12 12",
+    viewBox: 24,
+    stroke: true,
+    strokeWidth: 2
+  },
+  'chevron-down': {
+    d: "M6 9l6 6 6-6",
+    viewBox: 24,
+    stroke: true,
+    strokeWidth: 2
+  },
+  check: {
+    d: "M5 13l4 4L19 7",
+    viewBox: 24,
+    stroke: true,
+    strokeWidth: 2
+  }
+};
+
+const SVG_CHILD_TAGS: Record<string, boolean> = {
+  path: true,
+  circle: true,
+  rect: true,
+  line: true,
+  polyline: true,
+  polygon: true,
+  ellipse: true,
+  g: true,
+  use: true,
+  defs: true,
+  clippath: true,
+  mask: true,
+  marker: true,
+};
+
+// SVG attribute names that are camelCase in the spec and must NOT be
+// converted to kebab-case when serializing JSX props back to SVG. The default
+// transform (`viewBox` → `view-box`, `markerWidth` → `marker-width`, etc.)
+// produces invalid SVG attributes for these names. Presentation attributes
+// like `strokeWidth` / `strokeDasharray` ARE kebab-case in SVG, so they're
+// not in this set and continue to use the default conversion.
+const SVG_PRESERVE_CASE_ATTRS: Record<string, boolean> = {
+  viewBox: true,
+  preserveAspectRatio: true,
+  refX: true,
+  refY: true,
+  markerWidth: true,
+  markerHeight: true,
+  markerUnits: true,
+  gradientUnits: true,
+  gradientTransform: true,
+  patternUnits: true,
+  patternTransform: true,
+  patternContentUnits: true,
+};
+
+// ---------------------------------------------------------------------------
+// Helper Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert RGB to hex string
+ */
+export function rgbToHex(color: RGB): string {
+  const r = Math.round(Math.max(0, Math.min(1, color.r)) * 255);
+  const g = Math.round(Math.max(0, Math.min(1, color.g)) * 255);
+  const b = Math.round(Math.max(0, Math.min(1, color.b)) * 255);
+  return '#' + [r, g, b].map(x => x.toString(16).padStart(2, '0')).join('');
+}
+
+function escapeSvgAttr(value: string): string {
+  return String(value || '')
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function extractSvgAttribute(svg: string, attr: string): string | null {
+  const re = new RegExp('<svg[^>]*\\s' + attr + '=["\\\']([^"\\\']+)["\\\']', 'i');
+  const match = svg.match(re);
+  return match ? match[1] : null;
+}
+
+function hasMonochromeBlackPaint(svg: string): boolean {
+  const strokeMatch = /\sstroke=["']([^"']+)["']/i.exec(svg);
+  const fillMatch = /\sfill=["']([^"']+)["']/i.exec(svg);
+  const isBlack = (v: string | undefined): boolean => {
+    if (!v) return false;
+    const n = v.trim().toLowerCase();
+    return n === '#000' || n === '#000000' || n === 'black' || n === 'rgb(0,0,0)' || n === 'rgb(0, 0, 0)';
+  };
+  return isBlack(strokeMatch?.[1]) || isBlack(fillMatch?.[1]);
+}
+
+function normalizeSvgPaintValue(value: string | null): string | null {
+  if (!value) return null;
+  const lower = value.trim().toLowerCase();
+  if (lower === 'none') return null;
+  return value;
+}
+
+/**
+ * Flatten `<g>`'s stroke / fill / stroke-* attributes onto child shape
+ * elements that don't already set their own. Mirrors CSS inheritance.
+ *
+ * Why: Figma's `createNodeFromSvg` does NOT honor `<g>` attribute
+ * inheritance — a `<path>` inside `<g stroke="#X">` gets neither the
+ * stroke nor a fill, then the fallback paint logic in
+ * `createIconFromSvg` fills it with the icon color. The arrow-arc
+ * pattern (`<g stroke="currentColor"><path d="M..A.." stroke-dasharray="6 6"
+ * marker-end="..." /></g>`) was the canonical break: paths rendered as
+ * filled green wedges instead of dashed stroked arcs.
+ *
+ * Implementation: iteratively replace innermost `<g>` blocks (those
+ * containing no other `<g>`) with the same `<g>` but with inheritable
+ * attrs inlined onto child `<path>` / `<line>` / `<polyline>` / etc.
+ * After each pass the next-innermost `<g>` becomes innermost; repeat
+ * until stable.
+ */
+const SHAPE_TAGS_FOR_INHERIT = ['path', 'line', 'polyline', 'polygon', 'circle', 'rect', 'ellipse'];
+const SHAPE_TAGS_PATTERN = '(' + SHAPE_TAGS_FOR_INHERIT.join('|') + ')';
+const INHERITABLE_ATTRS = [
+  'stroke',
+  'stroke-width',
+  'stroke-linecap',
+  'stroke-linejoin',
+  'stroke-dasharray',
+  'fill',
+  // Opacity / fill-opacity / stroke-opacity are inherited per SVG spec
+  // and common in icon libraries that fade `<g>`-grouped paths
+  // (e.g. duotone Lucide variants, Heroicons solid/outline pairs).
+  'opacity',
+  'fill-opacity',
+  'stroke-opacity',
+];
+
+/**
+ * Inline inheritable attrs from the root `<svg>` element onto each shape
+ * child that doesn't already declare them. Run AFTER
+ * `flattenGroupInheritance` so any `<g>` overrides on the way down win
+ * first; only shapes still missing an attr fall back to the root.
+ *
+ * Why: many icon libraries set stroke / fill / stroke-width at the SVG
+ * root level (e.g. `<svg stroke="currentColor" fill="none"
+ * stroke-width="2">`). Figma's `createNodeFromSvg` doesn't propagate
+ * these to children — without this pass, every icon with that pattern
+ * loses its stroke styling.
+ */
+export function flattenSvgRootInheritance(svg: string): string {
+  const rootMatch = svg.match(/<svg\b([^>]*)>/i);
+  if (!rootMatch) return svg;
+  const rootAttrs = rootMatch[1];
+  const inherits: string[] = [];
+  for (const attr of INHERITABLE_ATTRS) {
+    const re = new RegExp('\\s' + attr + '=["\']([^"\']+)["\']', 'i');
+    const m = rootAttrs.match(re);
+    if (m) inherits.push(attr + '="' + m[1] + '"');
+  }
+  if (inherits.length === 0) return svg;
+  const shapeRe = new RegExp('<' + SHAPE_TAGS_PATTERN + '\\b([^>]*?)(/?)>', 'gi');
+  return svg.replace(shapeRe, function(shapeMatch, tagName, shapeAttrs, slash) {
+    const additions = inherits.filter(function(p) {
+      const name = p.split('=')[0];
+      return !new RegExp('\\s' + name + '=', 'i').test(shapeAttrs);
+    });
+    if (additions.length === 0) return shapeMatch;
+    return '<' + tagName + shapeAttrs + ' ' + additions.join(' ') + slash + '>';
+  });
+}
+
+export function flattenGroupInheritance(svg: string): string {
+  let prev: string;
+  let out = svg;
+  let safety = 32;
+  do {
+    prev = out;
+    // Match innermost <g> (the one with no nested <g> inside). Inline its
+    // inheritable attrs onto child shape elements that don't already declare
+    // their own, then STRIP those attrs from the <g> itself so it's no
+    // longer "innermost-with-inheritable-attrs" on the next pass. The next
+    // pass picks up the now-leaf outer <g>.
+    out = out.replace(
+      /<g\b([^>]*)>((?:(?!<g\b)[\s\S])*?)<\/g>/gi,
+      function(match, gAttrsRaw, gContent) {
+        let gAttrs = gAttrsRaw as string;
+        const inherits: string[] = [];
+        let strippedGAttrs = gAttrs;
+        for (const attr of INHERITABLE_ATTRS) {
+          const re = new RegExp('\\s' + attr + '=["\']([^"\']+)["\']', 'i');
+          const m = gAttrs.match(re);
+          if (m) {
+            inherits.push(attr + '="' + m[1] + '"');
+            strippedGAttrs = strippedGAttrs.replace(re, '');
+          }
+        }
+        if (inherits.length === 0) return match;
+        const shapeRe = new RegExp('<' + SHAPE_TAGS_PATTERN + '\\b([^>]*?)(/?)>', 'gi');
+        const inlined = (gContent as string).replace(shapeRe, function(shapeMatch, tagName, shapeAttrs, slash) {
+          // Filter out attrs the shape already declares — child's own value wins.
+          const additions = inherits.filter(function(p) {
+            const name = p.split('=')[0];
+            return !new RegExp('\\s' + name + '=', 'i').test(shapeAttrs);
+          });
+          if (additions.length === 0) return shapeMatch;
+          return '<' + tagName + shapeAttrs + ' ' + additions.join(' ') + slash + '>';
+        });
+        // If the <g> now has no remaining attrs, unwrap it so the outer <g>
+        // can be treated as innermost on the next pass.
+        if (strippedGAttrs.trim() === '') {
+          return inlined;
+        }
+        return '<g' + strippedGAttrs + '>' + inlined + '</g>';
+      }
+    );
+    safety--;
+  } while (out !== prev && safety > 0);
+  return out;
+}
+
+/**
+ * Inline SVG `<marker>` references — Figma's `createNodeFromSvg` does NOT
+ * render `marker-end` / `marker-start` / `marker-mid`, so arrowheads on
+ * paths silently disappear (canonical case: the round-trip arc arrows).
+ *
+ * For each `<path d="…" marker-end="url(#id)">` we:
+ *   1. Parse the `d` attribute to find the LAST command's endpoint and the
+ *      tangent direction at that endpoint.
+ *   2. Look up the `<marker>` definition by id.
+ *   3. Inject a `<g transform="translate(x y) rotate(θ) scale(sx sy)
+ *      translate(-refX -refY)">…</g>` containing the marker's inner SVG,
+ *      so it renders at the endpoint, rotated along the tangent.
+ *
+ * Currently handles M / L / A commands in `d` (covers the round-trip arc
+ * pattern). Circular arcs only (rx === ry, no x-axis rotation). Other path
+ * commands cause the marker to be skipped — better than an incorrect
+ * arrowhead orientation.
+ */
+type MarkerDef = {
+  viewBoxW: number;
+  viewBoxH: number;
+  refX: number;
+  refY: number;
+  markerWidth: number;
+  markerHeight: number;
+  markerUnits: 'strokeWidth' | 'userSpaceOnUse';
+  content: string;
+};
+
+function parseMarkerAttrs(svg: string): Map<string, MarkerDef> {
+  const result = new Map<string, MarkerDef>();
+  const re = /<marker\b([^>]*)>([\s\S]*?)<\/marker>/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(svg)) !== null) {
+    const attrs = m[1];
+    const inner = m[2].trim();
+    const idMatch = attrs.match(/\sid=["']([^"']+)["']/i);
+    if (!idMatch) continue;
+    const vbMatch = attrs.match(/\sviewBox=["']([^"']+)["']/i);
+    const vb = vbMatch ? vbMatch[1].trim().split(/[\s,]+/).map(parseFloat) : [0, 0, 10, 10];
+    const vbW = (vb.length >= 4 && Number.isFinite(vb[2])) ? vb[2] : 10;
+    const vbH = (vb.length >= 4 && Number.isFinite(vb[3])) ? vb[3] : 10;
+    const refXMatch = attrs.match(/\srefX=["']([^"']+)["']/i);
+    const refYMatch = attrs.match(/\srefY=["']([^"']+)["']/i);
+    const mwMatch = attrs.match(/\smarkerWidth=["']([^"']+)["']/i);
+    const mhMatch = attrs.match(/\smarkerHeight=["']([^"']+)["']/i);
+    const muMatch = attrs.match(/\smarkerUnits=["']([^"']+)["']/i);
+    // SVG default for `markerUnits` is `strokeWidth` — marker dimensions
+    // are scaled by the host path's stroke width. Without honouring this,
+    // markers render at literal markerWidth/markerHeight in user units,
+    // which is much smaller than the browser shows on a stroked path.
+    const markerUnits: 'strokeWidth' | 'userSpaceOnUse' =
+      muMatch && muMatch[1].toLowerCase() === 'userspaceonuse'
+        ? 'userSpaceOnUse'
+        : 'strokeWidth';
+    result.set(idMatch[1], {
+      viewBoxW: vbW,
+      viewBoxH: vbH,
+      refX: refXMatch ? parseFloat(refXMatch[1]) : 0,
+      refY: refYMatch ? parseFloat(refYMatch[1]) : 0,
+      markerWidth: mwMatch ? parseFloat(mwMatch[1]) : 3,
+      markerHeight: mhMatch ? parseFloat(mhMatch[1]) : 3,
+      markerUnits,
+      content: inner,
+    });
+  }
+  return result;
+}
+
+function parseMarkerRef(attr: string | undefined): string | null {
+  if (!attr) return null;
+  const m = attr.match(/url\(#([^)]+)\)/);
+  return m ? m[1] : null;
+}
+
+type PathSegment = {
+  cmd: string;
+  start: [number, number];
+  end: [number, number];
+  /** Last control point relative to the endpoint — direction (end - lastCtrl) is the tangent. */
+  lastCtrl?: [number, number];
+  arc?: number[];
+};
+
+function computePathEndpointAndTangent(d: string): { x: number; y: number; angleDeg: number } | null {
+  // Tokenise: capture command letters and signed numbers (incl. decimals).
+  const tokens = d.match(/[MLAHVCSQTZmlahvcsqtz]|[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g);
+  if (!tokens) return null;
+  let i = 0;
+  let cx = 0, cy = 0;
+  let startX = 0, startY = 0;
+  // Track previous quadratic control for T-command smoothing (reflection
+  // across the current point). Cubic S-command reflects the FIRST control
+  // from the previous segment — irrelevant for endpoint tangent (which
+  // depends only on the SECOND control), so not tracked.
+  let prevQuadraticCtrl: [number, number] | null = null;
+  let last: PathSegment | null = null;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (!/^[a-zA-Z]$/.test(t)) { i++; continue; }
+    const cmd = t;
+    const upper = cmd.toUpperCase();
+    const isRel = cmd !== upper;
+    i++;
+    if (upper === 'M' || upper === 'L') {
+      const x = parseFloat(tokens[i]);
+      const y = parseFloat(tokens[i + 1]);
+      i += 2;
+      const ex = isRel ? cx + x : x;
+      const ey = isRel ? cy + y : y;
+      last = { cmd: upper, start: [cx, cy], end: [ex, ey] };
+      cx = ex; cy = ey;
+      if (upper === 'M') { startX = ex; startY = ey; }
+      prevQuadraticCtrl = null;
+    } else if (upper === 'H') {
+      const x = parseFloat(tokens[i]);
+      i += 1;
+      const ex = isRel ? cx + x : x;
+      last = { cmd: 'L', start: [cx, cy], end: [ex, cy] };
+      cx = ex;
+      prevQuadraticCtrl = null;
+    } else if (upper === 'V') {
+      const y = parseFloat(tokens[i]);
+      i += 1;
+      const ey = isRel ? cy + y : y;
+      last = { cmd: 'L', start: [cx, cy], end: [cx, ey] };
+      cy = ey;
+      prevQuadraticCtrl = null;
+    } else if (upper === 'C') {
+      const x1 = parseFloat(tokens[i]);
+      const y1 = parseFloat(tokens[i + 1]);
+      const x2 = parseFloat(tokens[i + 2]);
+      const y2 = parseFloat(tokens[i + 3]);
+      const x = parseFloat(tokens[i + 4]);
+      const y = parseFloat(tokens[i + 5]);
+      i += 6;
+      const c1: [number, number] = [isRel ? cx + x1 : x1, isRel ? cy + y1 : y1];
+      const c2: [number, number] = [isRel ? cx + x2 : x2, isRel ? cy + y2 : y2];
+      const ex = isRel ? cx + x : x;
+      const ey = isRel ? cy + y : y;
+      last = { cmd: 'C', start: [cx, cy], end: [ex, ey], lastCtrl: c2 };
+      cx = ex; cy = ey;
+      // c1 is unused for tangent computation but tracked for completeness.
+      void c1;
+      prevQuadraticCtrl = null;
+    } else if (upper === 'S') {
+      const x2 = parseFloat(tokens[i]);
+      const y2 = parseFloat(tokens[i + 1]);
+      const x = parseFloat(tokens[i + 2]);
+      const y = parseFloat(tokens[i + 3]);
+      i += 4;
+      const c2: [number, number] = [isRel ? cx + x2 : x2, isRel ? cy + y2 : y2];
+      const ex = isRel ? cx + x : x;
+      const ey = isRel ? cy + y : y;
+      // Tangent at endpoint = (end - c2). Reflection of prev cubic ctrl
+      // would be the FIRST control for this segment, irrelevant for end
+      // tangent.
+      last = { cmd: 'S', start: [cx, cy], end: [ex, ey], lastCtrl: c2 };
+      cx = ex; cy = ey;
+      prevQuadraticCtrl = null;
+    } else if (upper === 'Q') {
+      const x1 = parseFloat(tokens[i]);
+      const y1 = parseFloat(tokens[i + 1]);
+      const x = parseFloat(tokens[i + 2]);
+      const y = parseFloat(tokens[i + 3]);
+      i += 4;
+      const c1: [number, number] = [isRel ? cx + x1 : x1, isRel ? cy + y1 : y1];
+      const ex = isRel ? cx + x : x;
+      const ey = isRel ? cy + y : y;
+      last = { cmd: 'Q', start: [cx, cy], end: [ex, ey], lastCtrl: c1 };
+      cx = ex; cy = ey;
+      prevQuadraticCtrl = c1;
+    } else if (upper === 'T') {
+      const x = parseFloat(tokens[i]);
+      const y = parseFloat(tokens[i + 1]);
+      i += 2;
+      // T's control point is the reflection of the previous quadratic
+      // control across the current point.
+      const c1: [number, number] = prevQuadraticCtrl
+        ? [2 * cx - prevQuadraticCtrl[0], 2 * cy - prevQuadraticCtrl[1]]
+        : [cx, cy];
+      const ex = isRel ? cx + x : x;
+      const ey = isRel ? cy + y : y;
+      last = { cmd: 'T', start: [cx, cy], end: [ex, ey], lastCtrl: c1 };
+      cx = ex; cy = ey;
+      prevQuadraticCtrl = c1;
+    } else if (upper === 'A') {
+      const rx = parseFloat(tokens[i]);
+      const ry = parseFloat(tokens[i + 1]);
+      const rot = parseFloat(tokens[i + 2]);
+      const lar = parseFloat(tokens[i + 3]);
+      const swp = parseFloat(tokens[i + 4]);
+      const x = parseFloat(tokens[i + 5]);
+      const y = parseFloat(tokens[i + 6]);
+      i += 7;
+      const ex = isRel ? cx + x : x;
+      const ey = isRel ? cy + y : y;
+      last = { cmd: 'A', start: [cx, cy], end: [ex, ey], arc: [rx, ry, rot, lar, swp] };
+      cx = ex; cy = ey;
+      prevQuadraticCtrl = null;
+    } else if (upper === 'Z') {
+      // Close path: line back to subpath start.
+      last = { cmd: 'L', start: [cx, cy], end: [startX, startY] };
+      cx = startX; cy = startY;
+      prevQuadraticCtrl = null;
+    } else {
+      // Unsupported command — abandon marker placement.
+      return null;
+    }
+  }
+  if (!last) return null;
+  let angle: number;
+  if (last.cmd === 'M' || last.cmd === 'L') {
+    const dx = last.end[0] - last.start[0];
+    const dy = last.end[1] - last.start[1];
+    if (dx === 0 && dy === 0) return null;
+    angle = Math.atan2(dy, dx);
+  } else if ((last.cmd === 'C' || last.cmd === 'S' || last.cmd === 'Q' || last.cmd === 'T') && last.lastCtrl) {
+    // For bezier curves the tangent at the endpoint is the direction from
+    // the last control point TO the endpoint.
+    const dx = last.end[0] - last.lastCtrl[0];
+    const dy = last.end[1] - last.lastCtrl[1];
+    if (dx === 0 && dy === 0) return null;
+    angle = Math.atan2(dy, dx);
+  } else if (last.cmd === 'A' && last.arc) {
+    const [rx, ry, rot, lar, swp] = last.arc;
+    if (Math.abs(rx - ry) > 0.001 || Math.abs(rot) > 0.001) return null;
+    const r = rx;
+    const [x1, y1] = last.start;
+    const [x2, y2] = last.end;
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const chord = Math.sqrt(dx * dx + dy * dy);
+    if (chord === 0 || chord > 2 * r + 0.001) return null;
+    const halfChord = chord / 2;
+    const h = Math.sqrt(Math.max(0, r * r - halfChord * halfChord));
+    // Perpendicular to chord (rotate (dx,dy) by 90° CCW in SVG y-down).
+    const px = -dy / chord;
+    const py = dx / chord;
+    // Center selection: lar XOR swp picks the opposite side.
+    const sign = (lar !== swp) ? 1 : -1;
+    const mx = (x1 + x2) / 2;
+    const my = (y1 + y2) / 2;
+    const centerX = mx + sign * h * px;
+    const centerY = my + sign * h * py;
+    const rdx = x2 - centerX;
+    const rdy = y2 - centerY;
+    // Tangent at endpoint = velocity along the path. For an arc
+    // parametrised as (cx + r*cos θ, cy + r*sin θ), velocity is
+    // (-r*sin θ, r*cos θ) = (-rdy, rdx) at the endpoint (since
+    // rdx = r*cos θ, rdy = r*sin θ). Sweep=1 means θ INCREASES along the
+    // path → that's the forward direction. Sweep=0 reverses it.
+    const tdx = (swp === 1) ? -rdy : rdy;
+    const tdy = (swp === 1) ? rdx : -rdx;
+    angle = Math.atan2(tdy, tdx);
+  } else {
+    return null;
+  }
+  return { x: last.end[0], y: last.end[1], angleDeg: angle * 180 / Math.PI };
+}
+
+function buildInlineMarkerGroup(
+  marker: MarkerDef,
+  x: number,
+  y: number,
+  angleDeg: number,
+  hostStrokeWidth: number
+): string {
+  // With `markerUnits="strokeWidth"` (the SVG default), the marker's box
+  // is multiplied by the host path's stroke width. With "userSpaceOnUse"
+  // markerWidth/markerHeight are taken as literal user-unit dimensions.
+  const unitsMultiplier = marker.markerUnits === 'strokeWidth' ? hostStrokeWidth : 1;
+  const sx = (marker.markerWidth * unitsMultiplier) / marker.viewBoxW;
+  const sy = (marker.markerHeight * unitsMultiplier) / marker.viewBoxH;
+  // Transform applies right-to-left in SVG; this matches the marker
+  // positioning spec: translate refX/refY of the (scaled, rotated) marker
+  // viewBox to (x, y) on the host path.
+  const t = `translate(${x} ${y}) rotate(${angleDeg}) scale(${sx} ${sy}) translate(${-marker.refX} ${-marker.refY})`;
+  return `<g transform="${t}">${marker.content}</g>`;
+}
+
+export function inlineSvgMarkers(svg: string): string {
+  const markers = parseMarkerAttrs(svg);
+  if (markers.size === 0) return svg;
+  const additions: string[] = [];
+  const pathRe = /<path\b([^>]*?)\/?>/gi;
+  let m: RegExpExecArray | null;
+  while ((m = pathRe.exec(svg)) !== null) {
+    const attrs = m[1];
+    const dMatch = attrs.match(/\sd=["']([^"']+)["']/i);
+    if (!dMatch) continue;
+    const markerEndMatch = attrs.match(/\smarker-end=["']([^"']+)["']/i);
+    const markerStartMatch = attrs.match(/\smarker-start=["']([^"']+)["']/i);
+    if (markerEndMatch) {
+      const id = parseMarkerRef(markerEndMatch[1]);
+      if (id && markers.has(id)) {
+        const pt = computePathEndpointAndTangent(dMatch[1]);
+        if (pt) {
+          // Extract host path's stroke-width — `flattenGroupInheritance`
+          // (run earlier in the pipeline) already inlined `<g>`'s
+          // stroke-width onto each child path, so reading the path's own
+          // attribute covers the inherited case too. Default to 1 per SVG
+          // spec when not set.
+          const swMatch = attrs.match(/\sstroke-width=["']([^"']+)["']/i);
+          const hostStrokeWidth = swMatch ? parseFloat(swMatch[1]) : 1;
+          additions.push(buildInlineMarkerGroup(
+            markers.get(id)!,
+            pt.x,
+            pt.y,
+            pt.angleDeg,
+            Number.isFinite(hostStrokeWidth) ? hostStrokeWidth : 1
+          ));
+        }
+      }
+    }
+    // marker-start handling could be added by reversing the path or
+    // tracking the first move/line tangent — not needed for round-trip's
+    // current arrow design (only marker-end is used).
+    void markerStartMatch;
+  }
+  if (additions.length === 0) return svg;
+  // Insert additions just before </svg> so they render on top (Figma
+  // honours document order for paint stacking).
+  return svg.replace(/<\/svg>/i, additions.join('') + '</svg>');
+}
+
+/**
+ * Preprocess SVG for Figma compatibility
+ * - Replaces "currentColor" with the actual hex color (Figma doesn't understand CSS currentColor)
+ * - Flattens `<g>` inheritance onto child shape elements (Figma's SVG
+ *   importer doesn't honor it)
+ * - Inlines `<marker>` references as transformed geometry at path
+ *   endpoints (Figma's SVG importer doesn't render markers)
+ */
+function preprocessSvgForFigma(svg: string, color?: RGB): string {
+  const hexColor = color ? rgbToHex(color) : '#000000';
+  let output = svg.replace(/currentColor/gi, hexColor);
+  output = output.replace(/\scolor=["'][^"']*["']/gi, '');
+  output = output.replace(/\sstyle=["']([^"']*)["']/gi, function(_match, rawStyles) {
+    const cleaned = String(rawStyles || '')
+      .split(';')
+      .map(s => s.trim())
+      .filter(Boolean)
+      .filter(s => s.toLowerCase().indexOf('color:') !== 0)
+      .join('; ');
+    if (!cleaned) return '';
+    return ' style="' + cleaned + '"';
+  });
+  output = flattenGroupInheritance(output);
+  output = flattenSvgRootInheritance(output);
+  output = inlineSvgMarkers(output);
+  const rootFill = normalizeSvgPaintValue(extractSvgAttribute(output, 'fill'));
+  const rootStroke = normalizeSvgPaintValue(extractSvgAttribute(output, 'stroke'));
+
+  output = output.replace(/<path\b([^>]*)>/gi, function(_match, rawAttrs) {
+    let attrs = rawAttrs || '';
+    let suffix = '';
+    if (attrs.trim().endsWith('/')) {
+      attrs = attrs.replace(/\s*\/$/, '');
+      suffix = ' /';
+    }
+
+    const hasFill = /\sfill=/.test(attrs);
+    const hasStroke = /\sstroke=/.test(attrs);
+
+    if (!hasStroke && rootStroke) {
+      attrs += ' stroke="' + rootStroke + '"';
+    }
+    if (!hasFill) {
+      if (!hasStroke && rootFill) {
+        attrs += ' fill="' + rootFill + '"';
+      } else if (!hasStroke && !rootFill && !rootStroke) {
+        attrs += ' fill="' + hexColor + '"';
+      }
+    }
+
+    return '<path' + attrs + suffix + '>';
+  });
+
+  return output;
+}
+
+// ---------------------------------------------------------------------------
+// SVG Node Manipulation
+// ---------------------------------------------------------------------------
+
+function collectVectors(node: SceneNode): VectorNode[] {
+  if (node.type === 'VECTOR') return [node];
+  if ('findAll' in node) {
+    return node.findAll((child) => child.type === 'VECTOR') as VectorNode[];
+  }
+  return [];
+}
+
+function getVectorPaintUsage(node: SceneNode): { hasFills: boolean; hasStrokes: boolean } {
+  let hasFills = false;
+  let hasStrokes = false;
+  for (const vector of collectVectors(node)) {
+    if (Array.isArray(vector.fills) && vector.fills.length > 0) hasFills = true;
+    if (Array.isArray(vector.strokes) && vector.strokes.length > 0) hasStrokes = true;
+  }
+  return { hasFills, hasStrokes };
+}
+
+function recolorIconPaint(node: SceneNode, color: RGB): void {
+  const paint: SolidPaint = { type: 'SOLID', color: { r: color.r, g: color.g, b: color.b } };
+  for (const vector of collectVectors(node)) {
+    if (Array.isArray(vector.fills) && vector.fills.length > 0) {
+      vector.fills = [paint];
+    }
+    if (Array.isArray(vector.strokes) && vector.strokes.length > 0) {
+      vector.strokes = [paint];
+    }
+  }
+}
+
+function applyIconPaint(
+  node: SceneNode,
+  color: RGB,
+  options: { stroke?: boolean; strokeWidth?: number } = {}
+): void {
+  for (const vector of collectVectors(node)) {
+    const paint: SolidPaint = { type: 'SOLID', color: { r: color.r, g: color.g, b: color.b } };
+    if (options.stroke) {
+      vector.strokes = [paint];
+      vector.strokeWeight = options.strokeWidth || vector.strokeWeight || 1.5;
+      vector.fills = [];
+    } else {
+      vector.fills = [paint];
+      vector.strokes = [];
+    }
+  }
+}
+
+export function normalizeIconNode(node: SceneNode): void {
+  if (!node) return;
+  if ('clipsContent' in node) node.clipsContent = false;
+  if ('layoutGrow' in node) node.layoutGrow = 0;
+  for (const vector of collectVectors(node)) {
+    if ('strokeAlign' in vector) {
+      try {
+        vector.strokeAlign = 'CENTER';
+      } catch (_err) {
+        // ignore
+      }
+    }
+  }
+}
+
+export function flattenSvgNode(node: SceneNode): VectorNode | null {
+  if (!node || !('children' in node)) return null;
+  const children = node.children;
+  if (!children.length) return null;
+  try {
+    const flattened = figma.flatten(Array.from(children));
+    flattened.name = node.name;
+    normalizeIconNode(flattened);
+    try {
+      const parent = node.parent;
+      if (parent && 'appendChild' in parent) {
+        parent.appendChild(flattened);
+      }
+      node.remove();
+    } catch (_err) {
+      // ignore
+    }
+    return flattened;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function resizeNode(node: SceneNode, width: number, height: number): void {
+  if ('resizeWithoutConstraints' in node) node.resizeWithoutConstraints(width, height);
+  else if ('resize' in node) node.resize(width, height);
+}
+
+export function resizeSvgNodeTo(node: SceneNode, width: number, height: number): void {
+  if (!node || width <= 0 || height <= 0) return;
+  if (node.type === 'VECTOR') {
+    resizeNode(node, width, height);
+    return;
+  }
+  const vectors = collectVectors(node);
+  const baseWidth = ('width' in node ? node.width : 0) || 0;
+  const baseHeight = ('height' in node ? node.height : 0) || 0;
+  if (!vectors.length || baseWidth <= 0 || baseHeight <= 0) {
+    resizeNode(node, width, height);
+    return;
+  }
+  const sx = width / baseWidth;
+  const sy = height / baseHeight;
+  for (const vector of vectors) {
+    resizeNode(vector, vector.width * sx, vector.height * sy);
+    if (typeof vector.x === 'number') vector.x = vector.x * sx;
+    if (typeof vector.y === 'number') vector.y = vector.y * sy;
+  }
+  resizeNode(node, width, height);
+}
+
+export function wrapIconNode(
+  icon: SceneNode,
+  width: number,
+  height: number,
+  pad: number,
+  name: string
+): FrameNode {
+  const wrapper = figma.createFrame();
+  wrapper.name = name;
+  wrapper.layoutMode = 'NONE';
+  wrapper.fills = [];
+  wrapper.strokes = [];
+  wrapper.resize(width, height);
+  wrapper.clipsContent = false;
+  if ('layoutGrow' in wrapper) wrapper.layoutGrow = 0;
+
+  const innerWidth = Math.max(1, width - pad * 2);
+  const innerHeight = Math.max(1, height - pad * 2);
+  if (innerWidth !== width || innerHeight !== height) {
+    resizeSvgNodeTo(icon, innerWidth, innerHeight);
+  }
+  normalizeIconNode(icon);
+  if ('x' in icon && 'width' in icon) icon.x = Math.round((width - icon.width) / 2);
+  if ('y' in icon && 'height' in icon) icon.y = Math.round((height - icon.height) / 2);
+  wrapper.appendChild(icon);
+  return wrapper;
+}
+
+// ---------------------------------------------------------------------------
+// Icon Creation Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an icon from the built-in ICON_PATHS
+ */
+export function createIcon(name: string, color: RGB): FrameNode | null {
+  const spec = ICON_PATHS[name];
+  if (!spec) return null;
+  const hexColor = color && typeof color.r === 'number' ? rgbToHex(color) : '#000000';
+  const strokeAttrs = spec.stroke
+    ? `fill="none" stroke="${hexColor}" stroke-width="${spec.strokeWidth || 1.5}" stroke-linecap="round" stroke-linejoin="round"`
+    : `fill="${hexColor}"`;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${spec.viewBox} ${spec.viewBox}"><path d="${spec.d}" ${strokeAttrs} /></svg>`;
+  const node = figma.createNodeFromSvg(svg);
+  node.name = `icon/${name}`;
+  normalizeIconNode(node);
+  // Keep the imported SVG frame so its original viewBox canvas is preserved.
+  // Flattening collapses to tight path bounds, which distorts icon proportions
+  // for sparse glyphs (for example chevrons) when resized to Tailwind sizes.
+  const target = node;
+  const usage = getVectorPaintUsage(target);
+  if (!usage.hasFills && !usage.hasStrokes) {
+    applyIconPaint(target, color, { stroke: spec.stroke, strokeWidth: spec.strokeWidth || 1.5 });
+  }
+  normalizeIconNode(target);
+  return target;
+}
+
+/**
+ * Create an icon from an SVG string
+ */
+export function createIconFromSvg(svg: string, color: RGB): FrameNode | null {
+  try {
+    // Registry SVGs from the scanner have `stroke="#000"` (or fill) baked in
+    // rather than `currentColor` — lucide-react sets currentColor at runtime,
+    // but renderToStaticMarkup resolves it to the default black. Treat those
+    // monochrome defaults as recolor candidates so icons pick up the
+    // caller's color like they would in the browser.
+    const usesCurrentColor = /currentcolor/i.test(svg) || hasMonochromeBlackPaint(svg);
+    const processedSvg = preprocessSvgForFigma(svg, color);
+    const node = figma.createNodeFromSvg(processedSvg);
+    node.name = 'icon/svg';
+    normalizeIconNode(node);
+
+    const vectors = collectVectors(node);
+    if (vectors.length === 0) {
+      node.remove();
+      return null;
+    }
+
+    // Keep the imported SVG frame so resize operations honor the source
+    // viewBox instead of scaling from tight vector bounds.
+    const target = node;
+
+    let finalUsage = getVectorPaintUsage(target);
+    if (usesCurrentColor && (finalUsage.hasFills || finalUsage.hasStrokes)) {
+      recolorIconPaint(target, color);
+      finalUsage = getVectorPaintUsage(target);
+    }
+    if (!finalUsage.hasFills && !finalUsage.hasStrokes) {
+      const svgHasStroke = /stroke=/.test(processedSvg) && !/stroke=["']none["']/i.test(processedSvg);
+      const svgHasFill = /fill=/.test(processedSvg) && !/fill=["']none["']/i.test(processedSvg);
+      applyIconPaint(target, color, { stroke: svgHasStroke && !svgHasFill });
+      finalUsage = getVectorPaintUsage(target);
+      if (!finalUsage.hasFills && !finalUsage.hasStrokes) {
+        target.remove();
+        return null;
+      }
+    }
+
+    normalizeIconNode(target);
+    return target;
+  } catch (_err) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// NodeIR to SVG Conversion
+// ---------------------------------------------------------------------------
+
+function nodeIrToSvgChild(node: NodeIR): string | null {
+  if (node.kind !== 'element') return null;
+
+  const tag = node.tagLower || '';
+  const props = node.props || {};
+
+  if (!SVG_CHILD_TAGS[tag]) {
+    const inner = (node.children || [])
+      .map(function(child) { return nodeIrToSvgChild(child); })
+      .filter(Boolean)
+      .join('');
+    return inner || null;
+  }
+
+  const attrs: string[] = [];
+  for (const key in props) {
+    if (props[key] == null) continue;
+    if (key === 'className') continue;
+    const attrKey = SVG_PRESERVE_CASE_ATTRS[key]
+      ? key
+      : key.replace(/[A-Z]/g, function(m) { return '-' + m.toLowerCase(); });
+    attrs.push(`${attrKey}="${escapeSvgAttr(props[key])}"`);
+  }
+
+  const inner = (node.children || [])
+    .map(function(child) { return nodeIrToSvgChild(child); })
+    .filter(Boolean)
+    .join('');
+  if (inner) {
+    return `<${tag}${attrs.length ? ' ' + attrs.join(' ') : ''}>${inner}</${tag}>`;
+  }
+  return `<${tag}${attrs.length ? ' ' + attrs.join(' ') : ''} />`;
+}
+
+export function nodeIrToSvg(node: NodeIR): string | null {
+  if (node.kind !== 'element' || node.tagLower !== 'svg') return null;
+
+  const attrs: string[] = [];
+  const props = node.props || {};
+
+  if (props.viewBox) attrs.push(`viewBox="${escapeSvgAttr(props.viewBox)}"`);
+  if (props.preserveAspectRatio) attrs.push(`preserveAspectRatio="${escapeSvgAttr(props.preserveAspectRatio)}"`);
+  if (props.width) attrs.push(`width="${escapeSvgAttr(props.width)}"`);
+  if (props.height) attrs.push(`height="${escapeSvgAttr(props.height)}"`);
+  if (props.fill) attrs.push(`fill="${escapeSvgAttr(props.fill)}"`);
+  if (props.stroke) attrs.push(`stroke="${escapeSvgAttr(props.stroke)}"`);
+  if (props['stroke-width']) attrs.push(`stroke-width="${escapeSvgAttr(props['stroke-width'])}"`);
+  if (props.strokeWidth) attrs.push(`stroke-width="${escapeSvgAttr(props.strokeWidth)}"`);
+  if (props['stroke-linecap']) attrs.push(`stroke-linecap="${escapeSvgAttr(props['stroke-linecap'])}"`);
+  if (props.strokeLinecap) attrs.push(`stroke-linecap="${escapeSvgAttr(props.strokeLinecap)}"`);
+  if (props['stroke-linejoin']) attrs.push(`stroke-linejoin="${escapeSvgAttr(props['stroke-linejoin'])}"`);
+  if (props.strokeLinejoin) attrs.push(`stroke-linejoin="${escapeSvgAttr(props.strokeLinejoin)}"`);
+
+  attrs.unshift(`xmlns="http://www.w3.org/2000/svg"`);
+
+  const children = (node.children || [])
+    .map(function(child) { return nodeIrToSvgChild(child); })
+    .filter(Boolean)
+    .join('');
+
+  const hasViewBox = !!props.viewBox;
+  const safeAttrs = hasViewBox ? attrs : attrs.concat(['viewBox="0 0 24 24"']);
+
+  return `<svg ${safeAttrs.join(' ')}>${children}</svg>`;
+}
+
+// ---------------------------------------------------------------------------
+// Size Resolution
+// ---------------------------------------------------------------------------
+
+function resolveSpacingToken(token: string): number | null {
+  const spacingScale = COMPONENT_DEFS && COMPONENT_DEFS.spacingScale ? COMPONENT_DEFS.spacingScale : {};
+  if (spacingScale && spacingScale[token] != null) return spacingScale[token];
+  const numeric = parseFloat(token);
+  if (!Number.isNaN(numeric)) return numeric * 4;
+  return null;
+}
+
+// Strips variant prefixes and returns the inner class. Different from
+// `tailwind/class-utils.ts#getBaseClass`, which rejects variant-prefixed
+// classes outright. Icon sizing applies even to hover/responsive variants.
+function stripVariantPrefix(cls: string): string | null {
+  if (!cls) return null;
+  const parts = cls.split(':');
+  return parts[parts.length - 1] || null;
+}
+
+export function resolveIconSizeFromClasses(classes: string[], props: Record<string, string>): { width: number; height: number } {
+  let width: number | null = null;
+  let height: number | null = null;
+
+  const parsePx = (value: string): number | null => {
+    const trimmed = value.trim();
+    // Percentage values (`width="100%"`) are NOT pixel sizes — they signal
+    // fill-parent intent (browser semantics). Returning `parseFloat` on
+    // them would yield `100`, mis-sizing e.g. `<svg width="100%" height="100%">`
+    // (the Bridge SVG) as a 100×100 icon. Skip; the caller falls back to
+    // the icon default + the layout pipeline's fill-parent handling
+    // (`applySvgLayoutMarksFromClasses` flags the wrap for resize).
+    if (/%\s*$/.test(trimmed)) return null;
+    const n = parseFloat(trimmed);
+    if (Number.isNaN(n)) return null;
+    return n;
+  };
+
+  if (props.size) {
+    const sizeValue = parsePx(props.size);
+    if (sizeValue != null) {
+      width = sizeValue;
+      height = sizeValue;
+    }
+  }
+
+  if (props.width) {
+    const w = parsePx(props.width);
+    if (w != null) width = w;
+  }
+  if (props.height) {
+    const h = parsePx(props.height);
+    if (h != null) height = h;
+  }
+
+  // Don't `break` on the first match — responsive variants ship MULTIPLE
+  // size-N classes in the resolved list (`size-10 size-14 size-16` after
+  // `resolveClassesForBreakpoint` keeps base + sm + lg at lg breakpoint).
+  // Tailwind / CSS semantics: last declaration wins. Picking the first
+  // (smallest) made every responsive view of an icon render at the base
+  // size.
+  for (const cls of classes) {
+    const base = stripVariantPrefix(cls);
+    if (!base) continue;
+    const sizeBracket = base.match(/^size-\[(\d+(?:\.\d+)?)px\]$/);
+    if (sizeBracket) {
+      const size = parseFloat(sizeBracket[1]);
+      width = size;
+      height = size;
+      continue;
+    }
+    const sizeToken = base.match(/^size-(\d+(?:\.\d+)?)$/);
+    if (sizeToken) {
+      const size = resolveSpacingToken(sizeToken[1]);
+      if (size != null) {
+        width = size;
+        height = size;
+      }
+    }
+  }
+
+  for (const cls of classes) {
+    const base = stripVariantPrefix(cls);
+    if (!base) continue;
+    const wBracket = base.match(/^w-\[(\d+(?:\.\d+)?)px\]$/);
+    if (wBracket) {
+      width = parseFloat(wBracket[1]);
+      continue;
+    }
+    const hBracket = base.match(/^h-\[(\d+(?:\.\d+)?)px\]$/);
+    if (hBracket) {
+      height = parseFloat(hBracket[1]);
+      continue;
+    }
+    const wToken = base.match(/^w-(\d+(?:\.\d+)?)$/);
+    if (wToken) {
+      const w = resolveSpacingToken(wToken[1]);
+      if (w != null) width = w;
+    }
+    const hToken = base.match(/^h-(\d+(?:\.\d+)?)$/);
+    if (hToken) {
+      const h = resolveSpacingToken(hToken[1]);
+      if (h != null) height = h;
+    }
+  }
+
+  if (width == null && height == null) {
+    width = 24;
+    height = 24;
+  } else if (width == null && height != null) {
+    width = height;
+  } else if (height == null && width != null) {
+    height = width;
+  }
+
+  return { width: width as number, height: height as number };
+}
+
+// Re-export for convenience
+export { getVectorPaintUsage };