@directededges/specs-from-figma 0.21.0 → 0.22.0

package/dist/Runtime/Context/interfaces.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ProcessingContext - Container for runtime services needed by Model
+ *
+ * Purpose: Internal context object for component processing
+ *
+ * Usage:
+ * - Created by Component factory methods
+ * - Passed to processing pipeline
+ * - Contains runtime environment info and data loaders
+ */
+import type { FigmaFoundations } from '../Foundations/interfaces.js';
+import type { FigmaNodes } from '../Nodes/interfaces.js';
+import type { LicenseResult } from '../../License/types.js';
+/**
+ * Runtime environment type
+ */
+export type RuntimeEnvironment = 'PLUGIN' | 'REST';
+/**
+ * Context object containing runtime services for Model processing
+ */
+export interface ProcessingContext {
+    /**
+     * Accessing styles and variables
+     */
+    foundations?: FigmaFoundations;
+    /**
+     * Node resolver for looking up nodes by ID
+     */
+    nodes?: FigmaNodes;
+    /**
+     * Runtime environment - determines API structure
+     * PLUGIN: Figma Plugin API (node.fontSize, node.fontName, etc.)
+     * REST: Figma REST API (node.style.fontSize, node.style.fontFamily, etc.)
+     */
+    runtime?: RuntimeEnvironment;
+    /**
+     * Author name for metadata attribution
+     * Falls back to figma.currentUser.name in Plugin, or "Unknown" if not provided
+     */
+    author?: string;
+    /**
+     * Resolved license outcome. Set once by the factory method before _process().
+     * Used throughout the pipeline to gate premium detection and output.
+     * Absent means free-tier (tier 0).
+     */
+    license?: LicenseResult;
+    /**
+     * Generator identity stamped into metadata.generator.
+     * Set by REST callers (CLI, etc.) to identify themselves.
+     * When absent, Metadata falls back to the plugin identity constants.
+     */
+    generator?: {
+        name: string;
+        version: string;
+        url: string;
+    };
+}
+/** PRO tier — public ecommerce (Tier 1) */
+export declare const PRO = 1;
+/** @internal ENTERPRISE tier (Tier 2) */
+export declare const ENTERPRISE = 2;
+/** @internal PARTNER tier (Tier 3) */
+export declare const PARTNER = 3;
+/**
+ * Null-safe tier check for license gating.
+ * Returns true when the context's license tier meets or exceeds the required tier.
+ * When context or license is absent, tier defaults to 0 (FREE).
+ *
+ * @param context - Processing context (may be undefined)
+ * @param requiredTier - Minimum tier needed (use PRO, ENTERPRISE, or PARTNER constants)
+ * @returns true if entitled
+ */
+export declare function entitled(context: ProcessingContext | undefined, requiredTier: number): boolean;

package/dist/Runtime/Foundations/FigmaPluginFoundations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * FigmaPluginFoundations - FigmaFoundations implementation for the Figma Plugin runtime.
+ *
+ * Purpose: Provides foundation data access (styles, variables, collections) using
+ * the figma.* global APIs. Lives here next to the FigmaFoundations interface and
+ * the REST adapter so both runtime implementations stay in lockstep; `figma.*` is
+ * referenced only inside methods, so bundling this into the CLI/REST build is
+ * inert (it is never instantiated there).
+ *
+ * Usage:
+ *   const loader = new FigmaPluginFoundations();
+ *   const style = await loader.getStyle('styleId');
+ *   const variable = await loader.getVariable('variableId');
+ */
+import type { VariableDefinition, VariableCollection, StyleDefinition, CodeSyntaxPlatform, FigmaFoundations } from './interfaces.js';
+export declare class FigmaPluginFoundations implements FigmaFoundations {
+    /**
+     * Get style by ID
+     */
+    getStyle(styleId: string): Promise<StyleDefinition | null>;
+    /**
+     * Get variable by ID
+     */
+    getVariable(variableId: string): Promise<VariableDefinition | null>;
+    /**
+     * Get variable collection by ID
+     */
+    getCollection(collectionId: string): Promise<VariableCollection | null>;
+    /**
+     * Get variable name with optional platform-specific code syntax
+     */
+    getVariableName(variableId: string, platform?: CodeSyntaxPlatform | 'DEFAULT'): Promise<string | null>;
+    /**
+     * Get collection name for a variable
+     */
+    getCollectionName(variableId: string): Promise<string | null>;
+}

package/dist/Runtime/Foundations/FigmaRESTFoundations.d.ts

@@ -0,0 +1,72 @@
+/**
+ * FigmaRESTDataResolver - REST API implementation of DataLoader interface
+ *
+ * Purpose: Provides DataLoader interface for pre-loaded REST API data
+ *
+ * Usage:
+ *   // Consumer builds Maps from their data sources
+ *   const variableMap = new Map<string, VariableDefinition>();
+ *   const collectionMap = new Map<string, VariableCollection>();
+ *   const styleMap = new Map<string, StyleDefinition>();
+ *
+ *   // Pass to constructor
+ *   const dataLoader = new FigmaRESTDataResolver(variableMap, collectionMap, styleMap);
+ *
+ *   // Use in ProcessingContext
+ *   await component.process(undefined, { dataLoader, ... });
+ *
+ * Note: Data loading/parsing is the consumer's responsibility (CLI/MCP).
+ * This class only provides runtime lookup via DataLoader interface.
+ */
+import type { FigmaFoundations, VariableDefinition, VariableCollection, StyleDefinition, CodeSyntaxPlatform } from './interfaces.js';
+export type VariableValue = boolean | number | string | RGB | VariableAlias;
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+export interface VariableAlias {
+    type: 'VARIABLE_ALIAS';
+    id: string;
+}
+export declare class FigmaRESTDataResolver implements FigmaFoundations {
+    private variableMap;
+    private collectionMap;
+    private styleMap;
+    constructor(variableMap: Map<string, VariableDefinition>, collectionMap: Map<string, VariableCollection>, styleMap: Map<string, StyleDefinition>);
+    /**
+     * Get variable name with optional platform-specific code syntax
+     */
+    getVariableName(variableId: string, platform?: CodeSyntaxPlatform | 'DEFAULT'): Promise<string | null>;
+    /**
+     * Get collection name for a variable
+     */
+    getCollectionName(variableId: string): Promise<string | null>;
+    /**
+     * Get style by ID
+     */
+    getStyle(styleId: string): Promise<StyleDefinition | null>;
+    /**
+     * Get variable by ID
+     */
+    getVariable(variableId: string): Promise<VariableDefinition | null>;
+    /**
+     * Get collection by ID
+     */
+    getCollection(collectionId: string): Promise<VariableCollection | null>;
+    /**
+     * Convert RGB color to hex string
+     */
+    static rgbToHex(color: RGB): string;
+    /**
+     * Populate variable style object with name and collection info
+     * Equivalent to Utilities.variableLookup() for REST API
+     */
+    populateVariableStyle(variableStyle: {
+        id: string;
+        name?: string;
+        collectionName?: string;
+        collectionId?: string;
+    }, codeSyntaxPlatform?: CodeSyntaxPlatform | 'DEFAULT', includeCollectionName?: boolean): Promise<void>;
+}

package/dist/Runtime/Foundations/FigmaRESTMaps.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Type definitions for external data structures
+ *
+ * These types define the shape of Maps passed from CLI/external environments
+ * to the transformer for styles, variables, and collections data.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Map type for styles data
+ * Matches DataLoader interface definition
+ */
+export type StylesMap = Map<string, {
+    id: string;
+    name: string;
+    type: 'FILL' | 'STROKE' | 'TEXT' | 'EFFECT' | 'GRID' | 'PAINT';
+    description?: string;
+    [key: string]: unknown;
+}>;
+/**
+ * Map type for variables data
+ * Matches DataLoader interface definition
+ */
+export type VariablesMap = Map<string, {
+    id: string;
+    name: string;
+    key: string;
+    variableCollectionId: string;
+    resolvedType: 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+    valuesByMode: Record<string, unknown>;
+    remote: boolean;
+    description?: string;
+    scopes?: string[];
+    codeSyntax?: {
+        WEB?: string;
+        ANDROID?: string;
+        iOS?: string;
+    };
+}>;
+/**
+ * Map type for variable collections data
+ * Matches DataLoader interface definition
+ */
+export type CollectionsMap = Map<string, {
+    id: string;
+    name: string;
+    key: string;
+    modes: Array<{
+        modeId: string;
+        name: string;
+    }>;
+    defaultModeId: string;
+    variableIds: string[];
+    remote: boolean;
+}>;

package/dist/Runtime/Foundations/interfaces.d.ts

@@ -0,0 +1,72 @@
+/**
+ * DataLoader - Interface for loading Figma data (styles, variables, collections)
+ *
+ * Purpose: Abstract data access to support both Plugin API and REST API sources
+ *
+ * Implementations:
+ * - PluginApiDataLoader: Uses figma.* global APIs in plugin environment
+ * - FigmaRESTDataResolver: Uses pre-loaded REST API JSON data
+ */
+export interface VariableDefinition {
+    id: string;
+    name: string;
+    key: string;
+    variableCollectionId: string;
+    resolvedType: 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+    valuesByMode: Record<string, unknown>;
+    remote: boolean;
+    description?: string;
+    scopes?: string[];
+    codeSyntax?: {
+        WEB?: string;
+        ANDROID?: string;
+        iOS?: string;
+    };
+    $custom?: Record<string, unknown>;
+}
+export interface VariableCollection {
+    id: string;
+    name: string;
+    key: string;
+    modes: Array<{
+        modeId: string;
+        name: string;
+    }>;
+    defaultModeId: string;
+    variableIds: string[];
+    remote: boolean;
+}
+export interface StyleDefinition {
+    id: string;
+    name: string;
+    type: 'FILL' | 'STROKE' | 'TEXT' | 'EFFECT' | 'GRID' | 'PAINT';
+    description?: string;
+    $custom?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export type CodeSyntaxPlatform = 'WEB' | 'ANDROID' | 'iOS';
+/**
+ * Data loader interface for accessing Figma styles and variables
+ */
+export interface FigmaFoundations {
+    /**
+     * Get style by ID
+     */
+    getStyle(styleId: string): Promise<StyleDefinition | null>;
+    /**
+     * Get variable by ID
+     */
+    getVariable(variableId: string): Promise<VariableDefinition | null>;
+    /**
+     * Get variable collection by ID
+     */
+    getCollection(collectionId: string): Promise<VariableCollection | null>;
+    /**
+     * Get variable name with optional platform-specific code syntax
+     */
+    getVariableName(variableId: string, platform: CodeSyntaxPlatform | 'DEFAULT'): Promise<string | null>;
+    /**
+     * Get collection name for a variable
+     */
+    getCollectionName(variableId: string): Promise<string | null>;
+}

package/dist/Runtime/Nodes/FigmaPluginNodes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * FigmaPluginNodes - FigmaNodes implementation for the Figma Plugin runtime.
+ *
+ * Purpose: Provides node lookup using the figma.* global APIs.
+ * Usage: Plugin runtime only — instantiated by the plugin and passed via
+ * ProcessingContext. Lives here (next to the FigmaNodes interface and the REST
+ * adapter) so both runtime implementations of the contract stay in lockstep;
+ * `figma.*` is referenced only inside methods, so bundling this into the CLI/REST
+ * build is inert (it is never instantiated there).
+ */
+import type { FigmaNodes, PageScanResult } from './interfaces.js';
+export declare class FigmaPluginNodes implements FigmaNodes {
+    /**
+     * Get node by ID using Plugin API
+     */
+    getNodeById(id: string): Promise<SceneNode | null>;
+    /**
+     * Get component name for instance swap property
+     * Returns component-set name if applicable, else component name, else null
+     */
+    getComponentNameForInstanceSwap(componentId: string): Promise<string | null>;
+    /**
+     * Get all sibling nodes on the same page that match the specified types.
+     * Traverses up to the page, then walks the page subtree collecting matching
+     * nodes. Descends into organizational containers (SECTION, FRAME, GROUP) so
+     * components nested inside them are found, but stops at any COMPONENT/
+     * COMPONENT_SET (never descends into a set's variants or a component's
+     * internals).
+     */
+    getPageSiblings(nodeId: string, types: string[]): Promise<PageScanResult[]>;
+    /**
+     * FILE-scope discovery (ADR-050) is not supported in the Figma plugin runtime:
+     * the plugin always uses PAGE scope (see SpecsController, which hard-codes
+     * `instanceExamples.scope = 'PAGE'`). This method exists only to satisfy the
+     * shared {@link FigmaNodes} interface — FILE scope is implemented by the REST
+     * runtime (FigmaRestNodes). It throws if ever invoked so that a future
+     * FILE-scope wiring fails loudly rather than silently returning nothing.
+     */
+    getAllPagesNodes(_types: string[]): Promise<PageScanResult[]>;
+    /**
+     * Recursive boundary walk shared by getPageSiblings and getAllPagesNodes.
+     * Descends SECTION/FRAME/GROUP; stops at COMPONENT/COMPONENT_SET/INSTANCE.
+     */
+    private _collectFromPage;
+}

package/dist/Runtime/Nodes/FigmaRestNodes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * FigmaRestNodes - FigmaNodes implementation for REST API data
+ *
+ * Purpose: Provides node lookup using NodeIndexer for offline/CLI processing
+ * Usage: CLI runtime only - instantiate with NodeIndexer and pass via ProcessingContext
+ */
+import type { FigmaNodes, PageScanResult } from './interfaces.js';
+import type { NodeIndexer } from '../../Adapters/RestApi/NodeIndexer.js';
+export declare class FigmaRestNodes implements FigmaNodes {
+    private indexer;
+    constructor(indexer: NodeIndexer);
+    /**
+     * Get node by ID
+     * Note: Returns null for REST mode since we don't have access to live Figma SceneNodes.
+     * Use specific methods like getComponentNameForInstanceSwap instead.
+     */
+    getNodeById(_id: string): Promise<SceneNode | null>;
+    /**
+     * Get component name for instance swap property
+     * Returns component-set name if applicable, else component name, else null
+     *
+     * Delegates to NodeIndexer.getComponentName which checks both tree-indexed
+     * components AND the REST API components/componentSets dictionaries.
+     */
+    getComponentNameForInstanceSwap(componentId: string): Promise<string | null>;
+    /**
+     * Get all nodes on the same page that match the specified types, found via a
+     * boundary-respecting recursive walk (descend SECTION/FRAME/GROUP, stop at
+     * COMPONENT/COMPONENT_SET/INSTANCE). Components nested inside organizational
+     * containers are found (subcomponent detection); a set's variants and a
+     * component's internals are not. Used for PAGE-scope discovery.
+     */
+    getPageSiblings(nodeId: string, types: string[]): Promise<PageScanResult[]>;
+    /**
+     * Get all nodes across every page in the file that match the given types,
+     * found via the same boundary-respecting recursive walk applied to every page.
+     * Does NOT use findAllByType (which would return deeply-nested matches inside
+     * components/instances). Used for FILE-scope discovery (ADR-050).
+     */
+    getAllPagesNodes(types: string[]): Promise<PageScanResult[]>;
+    /** Wrap a raw indexed node, attaching its immediate-parent name. */
+    private wrap;
+}

package/dist/Runtime/Nodes/NodeAccess.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-runtime node access helpers.
+ *
+ * Engine traversal walks raw node trees whose *shape* differs by runtime:
+ * REST data is plain JSON; the Figma plugin hands over live SceneNodes. Most
+ * properties (`type`, `children`) are shape-consistent, but a few are not —
+ * and reading those directly is how plane-2 divergence bugs slip in (they
+ * typecheck against the REST shape and fail silently in the plugin). Route the
+ * divergent reads through here so the cross-runtime handling lives in one
+ * tested place. See DirectedEdges/specs#116.
+ */
+/**
+ * Resolve an INSTANCE node's main-component id, cross-runtime.
+ *
+ * REST nodes carry `componentId` synchronously; live plugin InstanceNodes do
+ * not — they expose `getMainComponentAsync()`. Engine code that needs an
+ * instance's component identity MUST use this rather than reading `.componentId`
+ * directly, or plugin-runtime traversal silently fails to identify instances
+ * (the bug that broke nested slot-content capture in the plugin).
+ *
+ * @returns the component id, or `undefined` if it can't be resolved.
+ */
+export declare function resolveComponentId(node: unknown): Promise<string | undefined>;

package/dist/Runtime/Nodes/interfaces.d.ts

@@ -0,0 +1,60 @@
+/**
+ * NodeResolver - Interface for resolving Figma nodes by ID
+ *
+ * Purpose: Abstract node lookup to support both Plugin API and REST API sources
+ *
+ * Implementations:
+ * - PluginNodeResolver: Uses figma.getNodeByIdAsync() in plugin environment
+ * - RestNodeResolver: Uses NodeIndexer for REST API data
+ */
+import type { FigmaElementNode } from '../../Component/Nodes/types.js';
+/**
+ * A node surfaced by a page/file scan.
+ * - `node`: the runtime's processing-shaped node. For INSTANCE results this exposes
+ *   both `componentProperties` and `getMainComponentAsync` (REST: RestInstanceNode;
+ *   plugin: InstanceNode), so callers need no separate raw node.
+ * - `mainComponentId`: for INSTANCE nodes, the id of the component it is an instance of
+ *   (REST: `componentId`; plugin: resolved `mainComponent` id). Null for non-instances.
+ */
+export interface PageScanResult {
+    id: string;
+    name: string;
+    type: string;
+    parentName: string | null;
+    node: FigmaElementNode;
+    mainComponentId: string | null;
+}
+/**
+ * Node resolver interface for looking up nodes by ID
+ */
+export interface FigmaNodes {
+    /**
+     * Get node by ID
+     * @param id - Node ID to look up
+     * @returns Node if found, null otherwise
+     */
+    getNodeById(id: string): Promise<SceneNode | null>;
+    /**
+     * Get component name for instance swap property
+     * @param componentId - Component ID to look up
+     * @returns Component name (or component-set name if applicable), null if not found
+     */
+    getComponentNameForInstanceSwap(componentId: string): Promise<string | null>;
+    /**
+     * Get all sibling nodes on the same page that match the specified types.
+     * Used for page-level subcomponent discovery and PAGE-scope instance example detection.
+     * @param nodeId - The node whose page to scan
+     * @param types - Node types to filter (e.g. ['COMPONENT', 'COMPONENT_SET'])
+     * @returns Array of matching nodes (see {@link PageScanResult})
+     */
+    getPageSiblings(nodeId: string, types: string[]): Promise<PageScanResult[]>;
+    /**
+     * Get all nodes across every page in the file that match the specified types.
+     * Used for FILE-scope instance example detection (ADR-050).
+     * Runtime-agnostic: REST scans the indexed document; the plugin must implement
+     * this by iterating all pages.
+     * @param types - Node types to filter (e.g. ['INSTANCE', 'FRAME'])
+     * @returns Array of matching nodes (see {@link PageScanResult})
+     */
+    getAllPagesNodes(types: string[]): Promise<PageScanResult[]>;
+}

package/dist/Utilities/Utilities.d.ts

@@ -0,0 +1,44 @@
+import { ResolvedConfig } from '@directededges/specs-schema';
+type FormatKeys = ResolvedConfig['format']['keys'];
+import { SpecableNode } from '../Component/Nodes/types.js';
+export type FigmaVariantProp = {
+    name: string;
+    defaultValue: string;
+    options: string[];
+};
+export declare class Utilities {
+    private static readonly UNSAFE_CHARS_REGEX;
+    private static readonly WORD_SEPARATOR_REGEX;
+    private static readonly NON_ALPHANUMERIC_REGEX;
+    /**
+     * Converts a string to various naming formats commonly used in development
+     * @param str - The input string to convert
+     * @param format - The desired output format
+     * @returns The converted string
+     */
+    static formatKey(str: string, format?: FormatKeys): string;
+    static variantProps(node: SpecableNode): FigmaVariantProp[];
+    /**
+     * Match a name against a glyph pattern containing {i} placeholder.
+     * Returns the extracted portion if matched, or null if no match.
+     */
+    /** Normalize ` / ` separator spacing and collapse repeated whitespace in a layer/component name. */
+    static normalizeName(value: string): string;
+    /** Return `base`, or `base__2`, `base__3`, … until `isTaken` reports the key free. */
+    static disambiguateKey(base: string, isTaken: (key: string) => boolean): string;
+    /**
+     * Deterministic, runtime-agnostic string hash (cyrb53) returning a hex digest.
+     *
+     * Used for content-equality fingerprints (e.g. slot-content de-dup). Does NOT
+     * depend on `node:crypto`, which is unavailable in the Figma plugin sandbox —
+     * the plugin bundles the engine from source and stubs `node:crypto`, so a
+     * crypto-based hash silently collapses to a constant there. This pure-JS hash
+     * produces distinct digests in every runtime. Not cryptographically secure;
+     * only used for equality bucketing of small, bounded value sets.
+     */
+    static hashString(input: string): string;
+    static glyphPatternMatch(name: string, pattern: string): string | null;
+    static propertiesException(component: InstanceNode | SpecableNode): boolean;
+    static getPropertyDefinitions(component: InstanceNode | SpecableNode): Promise<ComponentPropertyDefinitions | 'exception'>;
+}
+export {};

package/dist/Utilities/types.ReferenceValue.d.ts

@@ -0,0 +1,16 @@
+/**
+ * JSON Reference value pointing to a prop configuration.
+ * Used when a property is bound to a component property.
+ */
+export interface ReferenceValue {
+    "$ref": string;
+}
+/**
+ * Type guard to check if a value is a ReferenceValue
+ */
+export declare function isReferenceValue(value: unknown): value is ReferenceValue;
+/**
+ * Keys for properties that can be bound to component props.
+ * Maps to Element properties: children, instanceOf, visible (in styles), text
+ */
+export type BindingKey = 'children' | 'instanceOf' | 'visible' | 'text';