@directededges/specs-from-figma 0.22.0 → 0.23.0

package/dist/Progress/ProgressCoordinator.d.ts

@@ -1,33 +0,0 @@
-import { ProgressCallback, ChunkInfo } from './Progress.js';
-import { PhaseConfiguration } from './PhaseConfiguration.js';
-/**
- * ProgressCoordinator wraps progress callback logic to keep Model/Output classes clean
- * Provides simple helper methods for notifying progress phases
- */
-export declare class ProgressCoordinator {
-    private callback?;
-    private config;
-    private currentStep;
-    private currentPhase;
-    constructor(config: PhaseConfiguration, callback?: ProgressCallback);
-    /**
-     * Notify that a phase has started
-     * Only increments step counter for new phases, not for chunks within a phase
-     * @param phase - Phase name from PHASE_NAMES
-     * @param chunkInfo - Optional chunk range for variant-heavy phases
-     */
-    notifyPhase(phase: string, chunkInfo?: ChunkInfo): Promise<void>;
-    /**
-     * Process items in chunks if they exceed threshold, automatically managing progress notifications
-     * Handles threshold detection and chunk range calculation internally
-     * @param items - Array of items to process
-     * @param phase - Phase name for progress display
-     * @param processor - Async function to process each chunk
-     */
-    forEachChunk<T>(items: T[], phase: string, processor: (chunk: T[]) => Promise<void>): Promise<void>;
-    /**
-     * Get current step number (useful for manual progress management)
-     * @returns Current step count
-     */
-    getCurrentStep(): number;
-}

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

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -1,23 +0,0 @@
-/**
- * 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

@@ -1,60 +0,0 @@
-/**
- * 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

@@ -1,44 +0,0 @@
-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

@@ -1,16 +0,0 @@
-/**
- * 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';