@sarjallab09/figma-intelligence 1.0.1 → 1.2.0

package/figma-intelligence-layer/src/tools/phase1-vision/screen-cloner/layout-segmenter.ts

@@ -1,18 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// Layout Segmenter  (Vision Pass 1)
-// Segments a screenshot into distinct UI layout zones using Claude Vision.
-// ─────────────────────────────────────────────────────────────────────────────
-
-import { VisionClient } from "../../../shared/vision-client.js";
-import { LayoutZone } from "../../../shared/types.js";
-
-/**
- * Segment a screenshot into layout zones using the Vision AI.
- * Returns an array of identified zones with bounding boxes.
- */
-export async function segmentLayout(
-  image: string,
-  vision: VisionClient
-): Promise<LayoutZone[]> {
-  return vision.segment(image);
-}

package/figma-intelligence-layer/src/tools/phase1-vision/screen-cloner/token-inferencer.ts

@@ -1,39 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// Token Inferencer
-// Takes raw pixel / color values from a ComponentManifest and snaps each
-// to the nearest design-system token using the snap algorithms from
-// token-utils.  This ensures generated frames use tokens, not raw values.
-// ─────────────────────────────────────────────────────────────────────────────
-
-import { ComponentManifest, TokenRef } from "../../../shared/types.js";
-import { snapToSpacingToken, snapToRadiusToken, snapToTypeToken } from "../../../shared/token-utils.js";
-
-export interface InferredTokens {
-  spacing: TokenRef;
-  radius?: TokenRef;
-  fontSize?: TokenRef;
-}
-
-/**
- * Snap raw values from a component manifest to the nearest design tokens.
- *
- * Token inference algorithm (from plan):
- *   rawSpacing  → Math.round(raw / 4) * 4 → nearest spacing token
- *   rawRadius   → snap to [0, 2, 4, 8, 12, 16, 24, 32] → nearest token
- *   rawFontSize → snap to type scale tokens → nearest token
- */
-export function inferTokens(manifest: ComponentManifest): InferredTokens {
-  const spacing = snapToSpacingToken(manifest.estimatedSpacing ?? 8);
-
-  const ext = manifest as unknown as Record<string, unknown>;
-
-  return {
-    spacing,
-    radius: ext.estimatedRadius != null
-      ? snapToRadiusToken(Number(ext.estimatedRadius))
-      : undefined,
-    fontSize: ext.estimatedFontSize != null
-      ? snapToTypeToken(Number(ext.estimatedFontSize))
-      : undefined,
-  };
-}

package/figma-intelligence-layer/src/tools/phase1-vision/screen-cloner/vision-pipeline.ts

@@ -1,58 +0,0 @@
-// ─────────────────────────────────────────────────────────────────────────────
-// Vision Pipeline
-// Orchestrates the multi-pass vision analysis for the screen cloner:
-//   Pass 1 → Layout segmentation (layout-segmenter)
-//   Pass 2 → Component identification per zone (component-recognizer)
-//   Token inference → snap raw px values to design tokens (token-inferencer)
-//   DS matching → fuzzy-match zones to real DS components (ds-matcher)
-// ─────────────────────────────────────────────────────────────────────────────
-
-import { VisionClient } from "../../../shared/vision-client.js";
-import { LayoutZone, ComponentManifest, ComponentSet } from "../../../shared/types.js";
-import { segmentLayout } from "./layout-segmenter.js";
-import { recognizeComponent } from "./component-recognizer.js";
-import { inferTokens, InferredTokens } from "./token-inferencer.js";
-import { matchToDesignSystem, DSMatchResult } from "./ds-matcher.js";
-
-export interface VisionPipelineResult {
-  zones: LayoutZone[];
-  manifests: ComponentManifest[];
-  tokenInferences: InferredTokens[];
-  dsMatches: DSMatchResult[];
-}
-
-/**
- * Runs the full multi-pass vision pipeline on a single image.
- *
- * @param image     base64 image string
- * @param vision    shared VisionClient instance
- * @param dsSets    available design system component sets for matching
- * @param cloneMode controls confidence threshold strictness
- */
-export async function runVisionPipeline(
-  image: string,
-  vision: VisionClient,
-  dsSets: ComponentSet[],
-  cloneMode: "pixel" | "system" | "adaptive"
-): Promise<VisionPipelineResult> {
-  // Pass 1 — Layout decomposition
-  const zones = await segmentLayout(image, vision);
-
-  // Pass 2 — Component recognition per zone
-  const manifests = await Promise.all(
-    zones.map((zone) => recognizeComponent(zone.zoneImage ?? image, vision))
-  );
-
-  // Token inference (spacing, color, radius, font-size snap)
-  const tokenInferences = manifests.map((m) => inferTokens(m));
-
-  // DS matching
-  const confidenceThreshold =
-    cloneMode === "pixel" ? 0.5 : cloneMode === "system" ? 0.85 : 0.75;
-
-  const dsMatches = manifests.map((m) =>
-    matchToDesignSystem(m, dsSets, confidenceThreshold)
-  );
-
-  return { zones, manifests, tokenInferences, dsMatches };
-}

package/figma-intelligence-layer/src/tools/phase1-vision/sketch-to-design/index.ts

@@ -1,298 +0,0 @@
-import fs from "fs/promises";
-import Fuse from "fuse.js";
-import { VisionClient } from "../../../shared/vision-client.js";
-import { getBridge } from "../../../shared/figma-bridge.js";
-import { decisionLog } from "../../../shared/decision-log.js";
-import { ComponentSet, LayoutZone, ComponentManifest } from "../../../shared/types.js";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Types
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface SketchToDesignArgs {
-  image: string;
-  productContext?: string;
-  strictDSOnly?: boolean;
-  frameWidth?: number;
-  annotateInterpretations?: boolean;
-}
-
-export interface SketchToDesignResult {
-  frameId: string;
-  zones: number;
-  matched: number;
-  unmatched: number;
-  unmatchedZones: string[];
-  tokenCoverage: string;
-  generatedFrame: { nodeId: string };
-  productContext: string;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Internal types
-// ─────────────────────────────────────────────────────────────────────────────
-
-interface ZoneMatch {
-  zone: LayoutZone & { intent?: string; layoutDirection?: string };
-  manifest: ComponentManifest;
-  dsComponent: ComponentSet | null;
-  confidence: number;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-async function resolveImage(image: string): Promise<string> {
-  if (image.startsWith("data:image") || image.startsWith("http")) {
-    return image;
-  }
-  const buf = await fs.readFile(image);
-  return `data:image/png;base64,${buf.toString("base64")}`;
-}
-
-function buildFuseIndex(componentSets: ComponentSet[]): Fuse<ComponentSet> {
-  return new Fuse(componentSets, {
-    keys: ["name", "description"],
-    threshold: 0.35,
-    includeScore: true,
-    minMatchCharLength: 2,
-  });
-}
-
-function matchZoneToDS(
-  fuse: Fuse<ComponentSet>,
-  manifest: ComponentManifest,
-  zone: LayoutZone & { intent?: string },
-  strictDSOnly: boolean
-): { component: ComponentSet | null; confidence: number } {
-  // Build a rich query from manifest and sketch zone intent
-  const queryParts = [
-    manifest.dsBestMatch,
-    manifest.componentType,
-    zone.intent,
-    zone.label,
-  ].filter(Boolean);
-
-  if (queryParts.length === 0) return { component: null, confidence: 0 };
-
-  const query = queryParts.join(" ");
-  const results = fuse.search(query);
-  if (results.length === 0) return { component: null, confidence: 0 };
-
-  const best = results[0];
-  const confidence = best.score !== undefined ? 1 - best.score : 0.5;
-
-  // In strict mode, only accept highly confident DS matches
-  const threshold = strictDSOnly ? 0.85 : 0.65;
-  return {
-    component: confidence >= threshold ? best.item : null,
-    confidence,
-  };
-}
-
-function buildFrameScript(
-  frameWidth: number,
-  matches: ZoneMatch[],
-  frameName: string,
-  annotateInterpretations: boolean
-): string {
-  const matchData = matches.map((m) => ({
-    label: m.zone.label,
-    layoutType: m.zone.layoutType,
-    intent: (m.zone as { intent?: string }).intent ?? null,
-    layoutDirection: (m.zone as { layoutDirection?: string }).layoutDirection ?? "horizontal",
-    dsId: m.dsComponent ? m.dsComponent.children[0]?.id ?? null : null,
-    dsName: m.dsComponent ? m.dsComponent.name : null,
-    confidence: m.confidence,
-    unmatched: m.dsComponent === null,
-  }));
-
-  return `
-(async () => {
-  const frameWidth = ${frameWidth};
-  const frameName = ${JSON.stringify(frameName)};
-  const annotateInterpretations = ${annotateInterpretations};
-  const matchData = ${JSON.stringify(matchData)};
-
-  // Create root auto-layout frame
-  const frame = figma.createFrame();
-  frame.name = frameName;
-  frame.resize(frameWidth, 900);
-  frame.layoutMode = "VERTICAL";
-  frame.primaryAxisSizingMode = "AUTO";
-  frame.counterAxisSizingMode = "FIXED";
-  frame.itemSpacing = 16;
-  frame.paddingLeft = 0;
-  frame.paddingRight = 0;
-  frame.paddingTop = 0;
-  frame.paddingBottom = 0;
-  frame.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }];
-  figma.currentPage.appendChild(frame);
-
-  const annotationStickyIds = [];
-
-  for (const m of matchData) {
-    let child;
-
-    if (!m.unmatched && m.dsId) {
-      const mainComp = await figma.getNodeByIdAsync(m.dsId);
-      if (mainComp && mainComp.type === "COMPONENT") {
-        child = mainComp.createInstance();
-        child.name = m.dsName || m.label;
-        child.layoutSizingHorizontal = "FILL";
-        frame.appendChild(child);
-      }
-    }
-
-    if (!child) {
-      // Placeholder for unmatched zones
-      child = figma.createFrame();
-      child.name = "Sketch zone: " + m.label;
-      child.resize(frameWidth, 80);
-      child.layoutSizingHorizontal = "FILL";
-      child.fills = [{ type: "SOLID", color: { r: 0.95, g: 0.95, b: 0.95 } }];
-      child.strokes = [{ type: "SOLID", color: { r: 0.6, g: 0.6, b: 0.6 } }];
-      child.strokeWeight = 1;
-      child.dashPattern = [8, 4];
-
-      // Add a label text inside the placeholder
-      const label = figma.createText();
-      await figma.loadFontAsync({ family: "Inter", style: "Regular" });
-      label.characters = m.label + (m.intent ? " — " + m.intent : "");
-      label.fontSize = 14;
-      label.fills = [{ type: "SOLID", color: { r: 0.4, g: 0.4, b: 0.4 } }];
-      label.x = 16;
-      label.y = 16;
-      child.appendChild(label);
-      frame.appendChild(child);
-    }
-
-    // Add interpretation sticky note for each zone
-    if (annotateInterpretations && child) {
-      const sticky = figma.createSticky();
-      const interpretText = [
-        "Zone: " + m.label,
-        m.intent ? "Intent: " + m.intent : null,
-        "Layout: " + m.layoutType + " (" + m.layoutDirection + ")",
-        m.dsName ? "DS: " + m.dsName + " (" + (m.confidence * 100).toFixed(0) + "% match)" : "No DS match",
-      ].filter(Boolean).join("\\n");
-      sticky.text.characters = interpretText;
-      sticky.x = frame.x + frameWidth + 24;
-      sticky.y = child.absoluteBoundingBox ? child.absoluteBoundingBox.y : frame.y;
-      figma.currentPage.appendChild(sticky);
-      annotationStickyIds.push(sticky.id);
-    }
-  }
-
-  figma.viewport.scrollAndZoomIntoView([frame]);
-  return { frameId: frame.id, nodeId: frame.id, annotationCount: annotationStickyIds.length };
-})();
-`;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Handler
-// ─────────────────────────────────────────────────────────────────────────────
-
-export async function sketchToDesignHandler(
-  args: SketchToDesignArgs
-): Promise<SketchToDesignResult> {
-  const {
-    image,
-    productContext = "General product UI",
-    strictDSOnly = false,
-    frameWidth = 1440,
-    annotateInterpretations = false,
-  } = args;
-
-  // 1. Resolve image to base64
-  const resolvedImage = await resolveImage(image);
-
-  // 2. Interpret sketch zones
-  const vision = new VisionClient();
-  const zones = await vision.interpretSketch(resolvedImage, productContext);
-
-  if (zones.length === 0) {
-    throw new Error(
-      "sketchToDesignHandler: VisionClient.interpretSketch() returned no zones — ensure the image contains a legible wireframe or sketch"
-    );
-  }
-
-  // 3. Identify each zone with component manifest
-  const manifests: ComponentManifest[] = await Promise.all(
-    zones.map((zone) => vision.identify(zone.zoneImage ?? resolvedImage))
-  );
-
-  // 4. Load DS components
-  const bridge = await getBridge();
-  const componentSets = await bridge.getComponentSets();
-
-  if (strictDSOnly && componentSets.length === 0) {
-    throw new Error(
-      "sketchToDesignHandler: strictDSOnly=true but no design system components found in this file"
-    );
-  }
-
-  // 5. Match each zone to a DS component
-  const fuse = buildFuseIndex(componentSets);
-  const matches: ZoneMatch[] = zones.map((zone, i) => {
-    const enrichedZone = zone as LayoutZone & { intent?: string; layoutDirection?: string };
-    const manifest = manifests[i];
-    const { component, confidence } = matchZoneToDS(fuse, manifest, enrichedZone, strictDSOnly);
-    return { zone: enrichedZone, manifest, dsComponent: component, confidence };
-  });
-
-  // 6. Build frame via bridge
-  const frameName = `[Sketch → Design] ${new Date().toLocaleDateString("en-US")} — ${productContext.slice(0, 40)}`;
-  const script = buildFrameScript(frameWidth, matches, frameName, annotateInterpretations);
-
-  const execResult = await bridge.execute(script);
-  if (!execResult.success) {
-    throw new Error(
-      `sketchToDesignHandler: Figma execution failed — ${execResult.error}`
-    );
-  }
-
-  const execData = execResult.result as { frameId: string; nodeId: string };
-
-  // 7. Compute stats
-  const matched = matches.filter((m) => m.dsComponent !== null).length;
-  const unmatched = matches.length - matched;
-  const unmatchedZones = matches
-    .filter((m) => m.dsComponent === null)
-    .map(
-      (m) =>
-        `${m.zone.label}${(m.zone as { intent?: string }).intent ? ` (${(m.zone as { intent?: string }).intent})` : ""} — confidence: ${m.confidence.toFixed(2)}`
-    );
-  const tokenCoverage =
-    zones.length > 0 ? `${Math.round((matched / zones.length) * 100)}%` : "0%";
-
-  // 8. Log action
-  await decisionLog.log({
-    tool: "figma_sketch_to_design",
-    nodeIds: [execData.frameId],
-    rationale: `Converted sketch to design with ${zones.length} zones. Product context: "${productContext}". DS coverage: ${tokenCoverage} (${matched}/${zones.length} matched). strictDSOnly: ${strictDSOnly}.`,
-    reversible: true,
-    metadata: {
-      productContext,
-      strictDSOnly,
-      frameWidth,
-      zones: zones.length,
-      matched,
-      unmatched,
-      unmatchedZones,
-    },
-  });
-
-  return {
-    frameId: execData.frameId,
-    zones: zones.length,
-    matched,
-    unmatched,
-    unmatchedZones,
-    tokenCoverage,
-    generatedFrame: { nodeId: execData.nodeId },
-    productContext,
-  };
-}

package/figma-intelligence-layer/src/tools/phase1-vision/visual-audit/index.ts

@@ -1,197 +0,0 @@
-import { VisionClient } from "../../../shared/vision-client.js";
-import { getBridge } from "../../../shared/figma-bridge.js";
-import { decisionLog } from "../../../shared/decision-log.js";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Types
-// ─────────────────────────────────────────────────────────────────────────────
-
-export type AuditArea = "hierarchy" | "contrast" | "density" | "brand" | "consistency";
-
-export interface VisualAuditArgs {
-  nodeId?: string;
-  imageInput?: string;
-  auditAreas: AuditArea[];
-  outputFormat: "report" | "annotations" | "both";
-}
-
-interface AuditIssue {
-  severity: "error" | "warning" | "suggestion";
-  description: string;
-  area: string;
-}
-
-export interface VisualAuditResult {
-  hierarchyScore: number;
-  cognitiveLoadRating: "low" | "medium" | "high";
-  brandAlignmentNotes: string;
-  consistencyIssues: string[];
-  overallScore: number;
-  topIssues: AuditIssue[];
-  estimatedFixTimeMinutes: number;
-  annotationPageId?: string;
-  auditAreas: AuditArea[];
-  nodeId?: string;
-  rawAnalysis?: Record<string, unknown>;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-function sanitiseAuditData(raw: Record<string, unknown>): VisualAuditResult {
-  return {
-    hierarchyScore: typeof raw.hierarchyScore === "number" ? raw.hierarchyScore : 50,
-    cognitiveLoadRating:
-      raw.cognitiveLoadRating === "low" ||
-      raw.cognitiveLoadRating === "medium" ||
-      raw.cognitiveLoadRating === "high"
-        ? (raw.cognitiveLoadRating as "low" | "medium" | "high")
-        : "medium",
-    brandAlignmentNotes:
-      typeof raw.brandAlignmentNotes === "string" ? raw.brandAlignmentNotes : "",
-    consistencyIssues: Array.isArray(raw.consistencyIssues)
-      ? (raw.consistencyIssues as string[])
-      : [],
-    overallScore: typeof raw.overallScore === "number" ? raw.overallScore : 50,
-    topIssues: Array.isArray(raw.topIssues)
-      ? (raw.topIssues as AuditIssue[])
-      : [],
-    estimatedFixTimeMinutes:
-      typeof raw.estimatedFixTimeMinutes === "number"
-        ? raw.estimatedFixTimeMinutes
-        : 0,
-    auditAreas: [],
-  };
-}
-
-function buildAnnotationScript(
-  issues: AuditIssue[],
-  pageName: string
-): string {
-  return `
-(async () => {
-  const pageName = ${JSON.stringify(pageName)};
-  const issues = ${JSON.stringify(issues)};
-
-  // Create or find the audit page
-  let auditPage = figma.root.children.find(p => p.name === pageName);
-  if (!auditPage) {
-    auditPage = figma.createPage();
-    auditPage.name = pageName;
-  }
-  await figma.setCurrentPageAsync(auditPage);
-
-  const severityColors = {
-    error:      { r: 0.96, g: 0.26, b: 0.21 },
-    warning:    { r: 1,    g: 0.76, b: 0    },
-    suggestion: { r: 0.13, g: 0.59, b: 0.95 },
-  };
-
-  const created = [];
-  issues.forEach((issue, idx) => {
-    const sticky = figma.createSticky();
-    sticky.text.characters =
-      "[" + issue.severity.toUpperCase() + "] " + issue.area + "\\n" + issue.description;
-    sticky.x = (idx % 4) * 320;
-    sticky.y = Math.floor(idx / 4) * 240;
-    const color = severityColors[issue.severity] || severityColors.suggestion;
-    sticky.fills = [{ type: "SOLID", color }];
-    auditPage.appendChild(sticky);
-    created.push(sticky.id);
-  });
-
-  const createdNodes = [];
-  for (const id of created) {
-    const n = await figma.getNodeByIdAsync(id);
-    if (n) createdNodes.push(n);
-  }
-  if (createdNodes.length > 0) figma.viewport.scrollAndZoomIntoView(createdNodes);
-
-  return { pageId: auditPage.id, count: created.length };
-})();
-`;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Handler
-// ─────────────────────────────────────────────────────────────────────────────
-
-export async function visualAuditHandler(
-  args: VisualAuditArgs
-): Promise<VisualAuditResult> {
-  const { nodeId, imageInput, auditAreas, outputFormat } = args;
-
-  if (!nodeId && !imageInput) {
-    throw new Error("visualAuditHandler: either nodeId or imageInput must be provided");
-  }
-
-  if (auditAreas.length === 0) {
-    throw new Error("visualAuditHandler: auditAreas must contain at least one area");
-  }
-
-  // 1. Resolve image — take screenshot from Figma if nodeId provided
-  let image: string;
-  if (nodeId) {
-    const bridge = await getBridge();
-    image = await bridge.takeScreenshot(nodeId);
-  } else {
-    image = imageInput!;
-  }
-
-  // 2. Run visual quality audit with VisionClient
-  const vision = new VisionClient();
-  const rawAudit = await vision.auditVisualQuality(image, auditAreas);
-
-  // 3. Build structured result
-  const result = sanitiseAuditData(rawAudit);
-  result.auditAreas = auditAreas;
-  if (nodeId) result.nodeId = nodeId;
-
-  let annotationPageId: string | undefined;
-
-  // 4. Create annotation page in Figma if requested
-  if (outputFormat === "annotations" || outputFormat === "both") {
-    if (result.topIssues.length > 0) {
-      const bridge = await getBridge();
-      const dateSuffix = new Date().toLocaleDateString("en-US", {
-        month: "short",
-        day: "numeric",
-        year: "numeric",
-      });
-      const pageName = `AI Audit — ${dateSuffix}`;
-      const script = buildAnnotationScript(result.topIssues, pageName);
-      const execResult = await bridge.execute(script);
-      if (!execResult.success) {
-        throw new Error(
-          `visualAuditHandler: Figma execution failed — ${execResult.error}`
-        );
-      }
-      const execData = execResult.result as { pageId: string };
-      annotationPageId = execData.pageId;
-      result.annotationPageId = annotationPageId;
-    }
-  }
-
-  // 5. Attach raw analysis only in report mode
-  if (outputFormat === "report" || outputFormat === "both") {
-    result.rawAnalysis = rawAudit;
-  }
-
-  // 6. Log action
-  const logNodeIds = [nodeId, annotationPageId].filter(Boolean) as string[];
-  await decisionLog.log({
-    tool: "figma_visual_audit",
-    nodeIds: logNodeIds,
-    rationale: `Visual audit completed. Areas: [${auditAreas.join(", ")}]. Overall score: ${result.overallScore}/100. Found ${result.topIssues.length} issues (cognitive load: ${result.cognitiveLoadRating}). Estimated fix time: ${result.estimatedFixTimeMinutes} min.`,
-    reversible: false,
-    metadata: {
-      outputFormat,
-      overallScore: result.overallScore,
-      issueCount: result.topIssues.length,
-      annotationPageId,
-    },
-  });
-
-  return result;
-}