@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/shared/prototype-script-builder.ts

@@ -0,0 +1,162 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Prototype Script Builder
+// Generates Figma Plugin API code strings for setting prototype reactions
+// with full trigger, animation, and navigation variety.  Used by both
+// figma_prototype_wire and figma_page_architect.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type TriggerType =
+  | "ON_CLICK"
+  | "ON_DRAG"
+  | "ON_HOVER"
+  | "AFTER_DELAY"
+  | "MOUSE_ENTER"
+  | "MOUSE_LEAVE";
+
+export type AnimationType =
+  | "SMART_ANIMATE"
+  | "DISSOLVE"
+  | "SLIDE_IN"
+  | "SLIDE_OUT"
+  | "PUSH"
+  | "MOVE_IN"
+  | "MOVE_OUT"
+  | "INSTANT";
+
+export type SlideDirection = "LEFT" | "RIGHT" | "TOP" | "BOTTOM";
+
+export type EasingType =
+  | "EASE_IN"
+  | "EASE_OUT"
+  | "EASE_IN_AND_OUT"
+  | "LINEAR";
+
+export type NavigationType =
+  | "NAVIGATE"
+  | "OVERLAY"
+  | "SWAP"
+  | "SCROLL_TO"
+  | "BACK"
+  | "CLOSE";
+
+export interface WireSpec {
+  fromNodeId: string;
+  toNodeId: string;
+  trigger: {
+    type: TriggerType;
+    delay?: number; // ms, for AFTER_DELAY
+  };
+  animation: {
+    type: AnimationType;
+    direction?: SlideDirection;
+    duration?: number; // seconds (Figma native), default 0.3
+    easing?: EasingType;
+  };
+  navigation?: NavigationType; // default NAVIGATE
+  preserveScrollPosition?: boolean;
+}
+
+export interface WireScriptResult {
+  fromNodeId: string;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Generate a single Figma Plugin API script that sets prototype reactions
+ * for all provided wire specs in one batch.  Preserves existing reactions.
+ */
+export function buildWireScript(specs: WireSpec[]): string {
+  const serialized = JSON.stringify(specs);
+
+  return `
+(async () => {
+  const specs = ${serialized};
+  const results = [];
+
+  for (const spec of specs) {
+    try {
+      const fromNode = await figma.getNodeByIdAsync(spec.fromNodeId);
+      const toNode = await figma.getNodeByIdAsync(spec.toNodeId);
+      if (!fromNode) {
+        results.push({ fromNodeId: spec.fromNodeId, success: false, error: "Source node not found" });
+        continue;
+      }
+      if (!toNode) {
+        results.push({ fromNodeId: spec.fromNodeId, success: false, error: "Destination node not found" });
+        continue;
+      }
+      if (!("reactions" in fromNode)) {
+        results.push({ fromNodeId: spec.fromNodeId, success: false, error: "Node does not support reactions" });
+        continue;
+      }
+
+      const trigger = { type: spec.trigger.type };
+      if (spec.trigger.type === "AFTER_DELAY" && spec.trigger.delay != null) {
+        trigger.delay = spec.trigger.delay;
+      }
+
+      const transition = {
+        type: spec.animation.type,
+        duration: spec.animation.duration != null ? spec.animation.duration : 0.3,
+        easing: { type: spec.animation.easing || "EASE_IN_AND_OUT" },
+      };
+      if (spec.animation.direction) {
+        transition.direction = spec.animation.direction;
+      }
+
+      const action = {
+        type: "NODE",
+        destinationId: spec.toNodeId,
+        navigation: spec.navigation || "NAVIGATE",
+        transition: transition,
+        preserveScrollPosition: !!spec.preserveScrollPosition,
+      };
+
+      const existing = fromNode.reactions || [];
+      fromNode.reactions = [...existing, { trigger, action }];
+
+      results.push({ fromNodeId: spec.fromNodeId, success: true });
+    } catch (e) {
+      results.push({ fromNodeId: spec.fromNodeId, success: false, error: e.message || String(e) });
+    }
+  }
+
+  return results;
+})();
+`.trim();
+}
+
+/**
+ * Generate a script that clears all reactions from the specified nodes.
+ */
+export function buildClearReactionsScript(nodeIds: string[]): string {
+  const serialized = JSON.stringify(nodeIds);
+
+  return `
+(async () => {
+  const nodeIds = ${serialized};
+  const results = [];
+
+  for (const id of nodeIds) {
+    try {
+      const node = await figma.getNodeByIdAsync(id);
+      if (!node) {
+        results.push({ nodeId: id, success: false, error: "Node not found" });
+        continue;
+      }
+      if (!("reactions" in node)) {
+        results.push({ nodeId: id, success: false, error: "Node does not support reactions" });
+        continue;
+      }
+      node.reactions = [];
+      results.push({ nodeId: id, success: true });
+    } catch (e) {
+      results.push({ nodeId: id, success: false, error: e.message || String(e) });
+    }
+  }
+
+  return results;
+})();
+`.trim();
+}

package/figma-intelligence-layer/src/shared/response-compression.ts

@@ -0,0 +1,440 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// P0: Adaptive Response Compression
+// 4-tier compression system to prevent context window overflow from large
+// Figma data payloads.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { FigmaNode, Token, ComponentSet } from "./types.js";
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export type CompressionTier = "full" | "summary" | "inventory" | "compact";
+
+export interface CompressionOptions {
+  forceTier?: CompressionTier;
+  maxSizeBytes?: number; // default 100KB for full
+}
+
+export interface CompressedResponse {
+  tier: CompressionTier;
+  originalSizeBytes: number;
+  compressedSizeBytes: number;
+  data: unknown;
+}
+
+// ─── Tier thresholds (bytes) ─────────────────────────────────────────────────
+
+const TIER_THRESHOLDS = {
+  full: 100_000,       // <100 KB
+  summary: 200_000,    // 100–200 KB
+  inventory: 500_000,  // 200–500 KB
+  // >500 KB → compact
+} as const;
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function byteSize(data: unknown): number {
+  try {
+    return new TextEncoder().encode(JSON.stringify(data)).byteLength;
+  } catch {
+    return Infinity; // unparseable → treat as very large
+  }
+}
+
+function determineTier(sizeBytes: number, maxFull?: number): CompressionTier {
+  const fullLimit = maxFull ?? TIER_THRESHOLDS.full;
+  if (sizeBytes < fullLimit) return "full";
+  if (sizeBytes < TIER_THRESHOLDS.summary) return "summary";
+  if (sizeBytes < TIER_THRESHOLDS.inventory) return "inventory";
+  return "compact";
+}
+
+function uniqueStrings(arr: string[]): string[] {
+  return [...new Set(arr)];
+}
+
+// ─── Node tree compression ──────────────────────────────────────────────────
+
+function summarizeNode(node: FigmaNode, depth: number, maxDepth: number): unknown {
+  const base: Record<string, unknown> = {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+  };
+
+  // Always keep dimensional / layout info
+  if (node.width !== undefined) base.width = node.width;
+  if (node.height !== undefined) base.height = node.height;
+  if (node.layoutMode !== undefined) base.layoutMode = node.layoutMode;
+
+  // Boolean flags instead of full detail arrays
+  if (node.fills && node.fills.length > 0) {
+    base.hasFills = true;
+    base.fillTypes = uniqueStrings(node.fills.map((f) => f.type));
+  }
+  if (node.strokes && node.strokes.length > 0) {
+    base.hasStrokes = true;
+    base.strokeTypes = uniqueStrings(node.strokes.map((s) => s.type));
+  }
+  if (node.effects && node.effects.length > 0) {
+    base.hasEffects = true;
+    base.effectCount = node.effects.length;
+  }
+  if (node.componentProperties) {
+    base.hasComponentProperties = true;
+  }
+
+  // Children handling
+  if (node.children && node.children.length > 0) {
+    if (depth < maxDepth) {
+      base.children = node.children.map((child) =>
+        summarizeNode(child, depth + 1, maxDepth),
+      );
+    } else {
+      base._childCount = node.children.length;
+      base._childTypes = uniqueStrings(node.children.map((c) => c.type));
+    }
+  }
+
+  return base;
+}
+
+function flattenNodes(node: FigmaNode): FigmaNode[] {
+  const result: FigmaNode[] = [node];
+  if (node.children) {
+    for (const child of node.children) {
+      result.push(...flattenNodes(child));
+    }
+  }
+  return result;
+}
+
+function inventoryNode(node: FigmaNode): unknown {
+  const allNodes = flattenNodes(node);
+  return allNodes.map((n) => ({
+    id: n.id,
+    name: n.name,
+    type: n.type,
+    childCount: n.children?.length ?? 0,
+    hasAutoLayout: n.layoutMode !== undefined && n.layoutMode !== "NONE",
+    hasFills: (n.fills?.length ?? 0) > 0,
+  }));
+}
+
+/**
+ * Compress a Figma node tree according to the specified tier.
+ */
+export function compressNodeTree(
+  node: FigmaNode,
+  tier: CompressionTier = "summary",
+): unknown {
+  if (tier === "full") return node;
+
+  if (tier === "summary") {
+    return summarizeNode(node, 0, 2);
+  }
+
+  if (tier === "inventory") {
+    return inventoryNode(node);
+  }
+
+  // compact
+  const allNodes = flattenNodes(node);
+  return allNodes.map((n) => ({ id: n.id, name: n.name, type: n.type }));
+}
+
+// ─── Token list compression ─────────────────────────────────────────────────
+
+/**
+ * Compress a list of design tokens according to the specified tier.
+ */
+export function compressTokenList(
+  tokens: Token[],
+  tier: CompressionTier = "summary",
+): unknown {
+  if (tier === "full") return tokens;
+
+  if (tier === "summary") {
+    return tokens.map((t) => ({
+      id: t.id,
+      name: t.name,
+      type: t.type,
+      value: t.value,
+      collectionId: t.collectionId,
+    }));
+  }
+
+  if (tier === "inventory") {
+    const byCollection = new Map<
+      string,
+      { collectionId: string; types: Set<string>; count: number }
+    >();
+
+    for (const token of tokens) {
+      const existing = byCollection.get(token.collectionId);
+      if (existing) {
+        existing.count += 1;
+        existing.types.add(token.type);
+      } else {
+        byCollection.set(token.collectionId, {
+          collectionId: token.collectionId,
+          types: new Set([token.type]),
+          count: 1,
+        });
+      }
+    }
+
+    return [...byCollection.values()].map((entry) => ({
+      collectionId: entry.collectionId,
+      tokenCount: entry.count,
+      types: [...entry.types],
+    }));
+  }
+
+  // compact
+  return tokens.map((t) => ({ id: t.id, name: t.name, type: t.type }));
+}
+
+// ─── Component sets compression ─────────────────────────────────────────────
+
+/**
+ * Compress component sets according to the specified tier.
+ */
+export function compressComponentSets(
+  sets: ComponentSet[],
+  tier: CompressionTier = "summary",
+): unknown {
+  if (tier === "full") return sets;
+
+  if (tier === "summary") {
+    return sets.map((s) => ({
+      id: s.id,
+      name: s.name,
+      description: s.description,
+      variantPropertyNames: Object.keys(s.variantGroupProperties ?? {}),
+      childCount: s.children?.length ?? 0,
+    }));
+  }
+
+  if (tier === "inventory") {
+    return sets.map((s) => ({
+      id: s.id,
+      name: s.name,
+      variantCount: s.children?.length ?? 0,
+      propertyNames: Object.keys(s.variantGroupProperties ?? {}),
+    }));
+  }
+
+  // compact
+  return sets.map((s) => ({ id: s.id, name: s.name }));
+}
+
+// ─── Data shape detection ───────────────────────────────────────────────────
+
+type DataShape = "nodeTree" | "tokenList" | "componentSetList" | "generic";
+
+function detectShape(data: unknown): DataShape {
+  if (data == null || typeof data !== "object") return "generic";
+
+  // Array shapes
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "generic";
+    const first = data[0] as Record<string, unknown>;
+
+    // Token list: objects with collectionId + type matching token types
+    if (
+      first &&
+      typeof first.collectionId === "string" &&
+      typeof first.type === "string"
+    ) {
+      return "tokenList";
+    }
+
+    // Component set list: objects with variantGroupProperties
+    if (first && typeof first.variantGroupProperties === "object") {
+      return "componentSetList";
+    }
+
+    return "generic";
+  }
+
+  // Single object shapes
+  const obj = data as Record<string, unknown>;
+
+  // Node tree: has id + type + possibly children
+  if (
+    typeof obj.id === "string" &&
+    typeof obj.type === "string" &&
+    typeof obj.name === "string"
+  ) {
+    // Distinguish node from component set
+    if (typeof obj.variantGroupProperties === "object") {
+      return "componentSetList"; // single component set — wrap when compressing
+    }
+    return "nodeTree";
+  }
+
+  return "generic";
+}
+
+// ─── Main entry point ───────────────────────────────────────────────────────
+
+/**
+ * Adaptively compress a Figma data payload so it fits comfortably inside an
+ * AI context window.
+ *
+ * 1. Measures the serialised byte size.
+ * 2. Selects an appropriate compression tier (or honours `forceTier`).
+ * 3. Detects the data shape and delegates to the correct compressor.
+ * 4. Returns metadata alongside the compressed payload.
+ */
+export function compressResponse(
+  data: unknown,
+  options?: CompressionOptions,
+): CompressedResponse {
+  const originalSizeBytes = byteSize(data);
+  const tier = options?.forceTier ?? determineTier(originalSizeBytes, options?.maxSizeBytes);
+
+  // Fast path — no compression needed
+  if (tier === "full") {
+    return {
+      tier,
+      originalSizeBytes,
+      compressedSizeBytes: originalSizeBytes,
+      data,
+    };
+  }
+
+  const shape = detectShape(data);
+  let compressed: unknown;
+
+  switch (shape) {
+    case "nodeTree":
+      compressed = compressNodeTree(data as FigmaNode, tier);
+      break;
+
+    case "tokenList":
+      compressed = compressTokenList(data as Token[], tier);
+      break;
+
+    case "componentSetList": {
+      // Handle both single set and array of sets
+      const sets = Array.isArray(data)
+        ? (data as ComponentSet[])
+        : [data as ComponentSet];
+      compressed = compressComponentSets(sets, tier);
+      break;
+    }
+
+    case "generic":
+    default:
+      // For unknown shapes, apply a best-effort generic trim
+      compressed = compressGeneric(data, tier);
+      break;
+  }
+
+  const compressedSizeBytes = byteSize(compressed);
+
+  return {
+    tier,
+    originalSizeBytes,
+    compressedSizeBytes,
+    data: compressed,
+  };
+}
+
+// ─── Generic fallback compression ───────────────────────────────────────────
+
+function compressGeneric(data: unknown, tier: CompressionTier): unknown {
+  if (data == null || typeof data !== "object") return data;
+
+  if (tier === "compact") {
+    // For arrays, keep only primitive summaries
+    if (Array.isArray(data)) {
+      return {
+        _type: "array",
+        _length: data.length,
+        _sampleKeys:
+          data.length > 0 && typeof data[0] === "object" && data[0] !== null
+            ? Object.keys(data[0])
+            : [],
+      };
+    }
+    // For objects, return top-level keys only
+    return {
+      _type: "object",
+      _keys: Object.keys(data),
+    };
+  }
+
+  if (tier === "inventory") {
+    if (Array.isArray(data)) {
+      return {
+        _type: "array",
+        _length: data.length,
+        _items: data.slice(0, 5).map((item) => {
+          if (item == null || typeof item !== "object") return item;
+          const obj = item as Record<string, unknown>;
+          const summary: Record<string, unknown> = {};
+          for (const key of Object.keys(obj)) {
+            const val = obj[key];
+            if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+              summary[key] = val;
+            } else if (Array.isArray(val)) {
+              summary[key] = `[Array(${val.length})]`;
+            } else if (typeof val === "object" && val !== null) {
+              summary[key] = `{Object(${Object.keys(val).length} keys)}`;
+            }
+          }
+          return summary;
+        }),
+      };
+    }
+    // Single object — shallow summary
+    const obj = data as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(obj)) {
+      const val = obj[key];
+      if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+        result[key] = val;
+      } else if (Array.isArray(val)) {
+        result[key] = `[Array(${val.length})]`;
+      } else if (typeof val === "object" && val !== null) {
+        result[key] = `{Object(${Object.keys(val).length} keys)}`;
+      }
+    }
+    return result;
+  }
+
+  // summary tier — trim nested objects to depth 2
+  return trimDepth(data, 0, 2);
+}
+
+function trimDepth(data: unknown, depth: number, maxDepth: number): unknown {
+  if (data == null || typeof data !== "object") return data;
+
+  if (Array.isArray(data)) {
+    if (depth >= maxDepth) {
+      return `[Array(${data.length})]`;
+    }
+    return data.map((item) => trimDepth(item, depth + 1, maxDepth));
+  }
+
+  const obj = data as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(obj)) {
+    const val = obj[key];
+    if (depth >= maxDepth) {
+      if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+        result[key] = val;
+      } else if (Array.isArray(val)) {
+        result[key] = `[Array(${val.length})]`;
+      } else if (typeof val === "object" && val !== null) {
+        result[key] = `{Object(${Object.keys(val).length} keys)}`;
+      }
+    } else {
+      result[key] = trimDepth(val, depth + 1, maxDepth);
+    }
+  }
+  return result;
+}