@biela.dev/ai-bridge 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,193 @@
+import { DeviceLayoutContract } from '@biela.dev/devices';
+
+/**
+ * Serialize a Device Layout Contract into a complete AI instruction prompt.
+ *
+ * This is the core of the AI Bridge — it converts structured device data
+ * into precise natural language instructions that Claude can follow to
+ * generate pixel-perfect mobile UI components.
+ */
+declare function serializeDLCForAI(dlc: DeviceLayoutContract, appDescription: string): string;
+
+/** Result of UI generation */
+interface GenerationResult {
+    code: string;
+    contract: DeviceLayoutContract;
+    metadata: {
+        device: string;
+        generatedAt: string;
+        promptUsed: string;
+        enrichedDescription: string;
+    };
+}
+/** Parameters for generateMobileUI */
+interface GenerateMobileUIParams {
+    deviceId: string;
+    appDescription: string;
+    orientation?: "portrait";
+    style?: "ios-native" | "android-native" | "custom";
+    darkMode?: boolean;
+    /** Claude API key — falls back to CLAUDE_API_KEY env var */
+    claudeApiKey?: string;
+}
+/** Parameters for refineUI */
+interface RefineUIParams {
+    previousCode: string;
+    contract: DeviceLayoutContract;
+    refinementInstruction: string;
+    claudeApiKey?: string;
+}
+/** Result of UI refinement */
+interface RefinementResult {
+    code: string;
+    changesSummary: string;
+}
+/** Validation result from validateGeneratedUI */
+interface ValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+
+/**
+ * Compact DLC summary for refinement prompts (prompt #2+).
+ *
+ * Instead of re-sending the full ~2000-token DLC prompt on every turn,
+ * this produces a short reminder (~200 tokens) with just the device ID,
+ * dimensions, and any validation errors/warnings from the previous render.
+ */
+declare function serializeCompactDLC(dlc: DeviceLayoutContract, validation?: ValidationResult): string;
+
+/**
+ * Validate generated UI code against a Device Layout Contract.
+ *
+ * Performs static analysis on the code string to catch common constraint
+ * violations before rendering. This is a best-effort check — it catches
+ * obvious issues but can't guarantee pixel-perfect compliance.
+ */
+declare function validateGeneratedUI(code: string, dlc: DeviceLayoutContract): ValidationResult;
+
+/**
+ * Enrich a short app description into a detailed feature specification.
+ *
+ * Takes a brief prompt like "a banking app" and returns a 150-200 word
+ * structured specification including screens, navigation patterns,
+ * data types, and interactions appropriate for the target platform.
+ */
+declare function enrichAppDescription(rawPrompt: string, dlc: DeviceLayoutContract, apiKey?: string): Promise<string>;
+
+/**
+ * Generate a mobile UI component for a specific device.
+ *
+ * Full pipeline: device lookup → DLC retrieval → description enrichment →
+ * prompt serialization → Claude API call → code extraction → validation.
+ */
+declare function generateMobileUI(params: GenerateMobileUIParams): Promise<GenerationResult>;
+/**
+ * Refine a previously generated UI component.
+ *
+ * Enables iterative improvements without re-running the full generation
+ * pipeline. Sends the previous code + refinement instruction to Claude.
+ */
+declare function refineUI(params: RefineUIParams): Promise<RefinementResult>;
+
+/**
+ * Tracks prompt session state to determine whether to send the full DLC
+ * injection (first prompt) or a compact summary (subsequent prompts).
+ *
+ * Usage:
+ *   const session = createPromptSession(dlc, "a banking app");
+ *   session.getInjection();  // → full DLC prompt (first time)
+ *   session.getInjection();  // → compact summary (second time onward)
+ *   session.getInjection({ validation }); // → compact + validation feedback
+ *   session.switchDevice(newDlc); // → resets to full prompt for new device
+ */
+interface PromptSession {
+    /** Get the appropriate injection for the current turn. */
+    getInjection(opts?: {
+        validation?: ValidationResult;
+    }): string;
+    /** How many prompts have been sent in this session. */
+    getTurnCount(): number;
+    /** Whether this is the first prompt (full DLC will be sent). */
+    isFirstTurn(): boolean;
+    /** Switch to a different device — resets the session so the next injection is full. */
+    switchDevice(dlc: DeviceLayoutContract): void;
+    /** Get the current device contract. */
+    getContract(): DeviceLayoutContract;
+    /** Force the next injection to be a full DLC prompt (useful after settings changes). */
+    resetToFull(): void;
+    /** Get history of all injections sent. */
+    getHistory(): PromptHistoryEntry[];
+}
+interface PromptHistoryEntry {
+    turn: number;
+    type: "full" | "compact";
+    deviceId: string;
+    injection: string;
+    timestamp: number;
+}
+declare function createPromptSession(initialDlc: DeviceLayoutContract, appDescription: string): PromptSession;
+
+/**
+ * Injection settings — configurable overrides for the DLC prompt injection.
+ *
+ * Lets users customize what gets injected, toggle integration modes,
+ * and add custom constraints or remove default ones.
+ */
+interface InjectionSettings {
+    /** Integration modes — toggle on/off */
+    modes: {
+        /** NPM SDK mode: serializeDLCForAI() + validateGeneratedUI() used as imports */
+        sdk: boolean;
+        /** API mode: Studio exposes DLC over local HTTP/WebSocket */
+        api: boolean;
+        /** Built-in generation: generateMobileUI() calls Claude directly */
+        builtinGeneration: boolean;
+    };
+    /** Prompt customization */
+    prompt: {
+        /** Additional constraints to append to the DLC prompt */
+        extraConstraints: string[];
+        /** Constraints to suppress from the default DLC prompt (matched by substring) */
+        suppressedConstraints: string[];
+        /** Custom app description prefix (prepended to user's description) */
+        descriptionPrefix: string;
+        /** Custom app description suffix (appended to user's description) */
+        descriptionSuffix: string;
+        /** Override the design language instruction */
+        designLanguageOverride: string | null;
+        /** Override the output requirements section entirely */
+        outputRequirementsOverride: string[] | null;
+    };
+    /** Validation settings */
+    validation: {
+        /** Treat warnings as errors */
+        strictMode: boolean;
+        /** Disable specific warning checks by ID */
+        suppressedWarnings: string[];
+        /** Auto-inject validation feedback into refinement prompts */
+        autoFeedback: boolean;
+    };
+    /** API server settings (when api mode is enabled) */
+    apiServer: {
+        port: number;
+        host: string;
+    };
+}
+declare function createDefaultSettings(): InjectionSettings;
+/**
+ * Apply injection settings to modify a generated prompt.
+ * Processes suppressions and additions.
+ */
+declare function applySettingsToPrompt(prompt: string, settings: InjectionSettings): string;
+/**
+ * Serialize settings to JSON for persistence (localStorage, file, etc.)
+ */
+declare function serializeSettings(settings: InjectionSettings): string;
+/**
+ * Deserialize settings from JSON, merging with defaults for missing fields.
+ */
+declare function deserializeSettings(json: string): InjectionSettings;
+
+export { type GenerateMobileUIParams, type GenerationResult, type InjectionSettings, type PromptHistoryEntry, type PromptSession, type RefineUIParams, type RefinementResult, type ValidationResult, applySettingsToPrompt, createDefaultSettings, createPromptSession, deserializeSettings, enrichAppDescription, generateMobileUI, refineUI, serializeCompactDLC, serializeDLCForAI, serializeSettings, validateGeneratedUI };

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+import { DeviceLayoutContract } from '@biela.dev/devices';
+
+/**
+ * Serialize a Device Layout Contract into a complete AI instruction prompt.
+ *
+ * This is the core of the AI Bridge — it converts structured device data
+ * into precise natural language instructions that Claude can follow to
+ * generate pixel-perfect mobile UI components.
+ */
+declare function serializeDLCForAI(dlc: DeviceLayoutContract, appDescription: string): string;
+
+/** Result of UI generation */
+interface GenerationResult {
+    code: string;
+    contract: DeviceLayoutContract;
+    metadata: {
+        device: string;
+        generatedAt: string;
+        promptUsed: string;
+        enrichedDescription: string;
+    };
+}
+/** Parameters for generateMobileUI */
+interface GenerateMobileUIParams {
+    deviceId: string;
+    appDescription: string;
+    orientation?: "portrait";
+    style?: "ios-native" | "android-native" | "custom";
+    darkMode?: boolean;
+    /** Claude API key — falls back to CLAUDE_API_KEY env var */
+    claudeApiKey?: string;
+}
+/** Parameters for refineUI */
+interface RefineUIParams {
+    previousCode: string;
+    contract: DeviceLayoutContract;
+    refinementInstruction: string;
+    claudeApiKey?: string;
+}
+/** Result of UI refinement */
+interface RefinementResult {
+    code: string;
+    changesSummary: string;
+}
+/** Validation result from validateGeneratedUI */
+interface ValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+}
+
+/**
+ * Compact DLC summary for refinement prompts (prompt #2+).
+ *
+ * Instead of re-sending the full ~2000-token DLC prompt on every turn,
+ * this produces a short reminder (~200 tokens) with just the device ID,
+ * dimensions, and any validation errors/warnings from the previous render.
+ */
+declare function serializeCompactDLC(dlc: DeviceLayoutContract, validation?: ValidationResult): string;
+
+/**
+ * Validate generated UI code against a Device Layout Contract.
+ *
+ * Performs static analysis on the code string to catch common constraint
+ * violations before rendering. This is a best-effort check — it catches
+ * obvious issues but can't guarantee pixel-perfect compliance.
+ */
+declare function validateGeneratedUI(code: string, dlc: DeviceLayoutContract): ValidationResult;
+
+/**
+ * Enrich a short app description into a detailed feature specification.
+ *
+ * Takes a brief prompt like "a banking app" and returns a 150-200 word
+ * structured specification including screens, navigation patterns,
+ * data types, and interactions appropriate for the target platform.
+ */
+declare function enrichAppDescription(rawPrompt: string, dlc: DeviceLayoutContract, apiKey?: string): Promise<string>;
+
+/**
+ * Generate a mobile UI component for a specific device.
+ *
+ * Full pipeline: device lookup → DLC retrieval → description enrichment →
+ * prompt serialization → Claude API call → code extraction → validation.
+ */
+declare function generateMobileUI(params: GenerateMobileUIParams): Promise<GenerationResult>;
+/**
+ * Refine a previously generated UI component.
+ *
+ * Enables iterative improvements without re-running the full generation
+ * pipeline. Sends the previous code + refinement instruction to Claude.
+ */
+declare function refineUI(params: RefineUIParams): Promise<RefinementResult>;
+
+/**
+ * Tracks prompt session state to determine whether to send the full DLC
+ * injection (first prompt) or a compact summary (subsequent prompts).
+ *
+ * Usage:
+ *   const session = createPromptSession(dlc, "a banking app");
+ *   session.getInjection();  // → full DLC prompt (first time)
+ *   session.getInjection();  // → compact summary (second time onward)
+ *   session.getInjection({ validation }); // → compact + validation feedback
+ *   session.switchDevice(newDlc); // → resets to full prompt for new device
+ */
+interface PromptSession {
+    /** Get the appropriate injection for the current turn. */
+    getInjection(opts?: {
+        validation?: ValidationResult;
+    }): string;
+    /** How many prompts have been sent in this session. */
+    getTurnCount(): number;
+    /** Whether this is the first prompt (full DLC will be sent). */
+    isFirstTurn(): boolean;
+    /** Switch to a different device — resets the session so the next injection is full. */
+    switchDevice(dlc: DeviceLayoutContract): void;
+    /** Get the current device contract. */
+    getContract(): DeviceLayoutContract;
+    /** Force the next injection to be a full DLC prompt (useful after settings changes). */
+    resetToFull(): void;
+    /** Get history of all injections sent. */
+    getHistory(): PromptHistoryEntry[];
+}
+interface PromptHistoryEntry {
+    turn: number;
+    type: "full" | "compact";
+    deviceId: string;
+    injection: string;
+    timestamp: number;
+}
+declare function createPromptSession(initialDlc: DeviceLayoutContract, appDescription: string): PromptSession;
+
+/**
+ * Injection settings — configurable overrides for the DLC prompt injection.
+ *
+ * Lets users customize what gets injected, toggle integration modes,
+ * and add custom constraints or remove default ones.
+ */
+interface InjectionSettings {
+    /** Integration modes — toggle on/off */
+    modes: {
+        /** NPM SDK mode: serializeDLCForAI() + validateGeneratedUI() used as imports */
+        sdk: boolean;
+        /** API mode: Studio exposes DLC over local HTTP/WebSocket */
+        api: boolean;
+        /** Built-in generation: generateMobileUI() calls Claude directly */
+        builtinGeneration: boolean;
+    };
+    /** Prompt customization */
+    prompt: {
+        /** Additional constraints to append to the DLC prompt */
+        extraConstraints: string[];
+        /** Constraints to suppress from the default DLC prompt (matched by substring) */
+        suppressedConstraints: string[];
+        /** Custom app description prefix (prepended to user's description) */
+        descriptionPrefix: string;
+        /** Custom app description suffix (appended to user's description) */
+        descriptionSuffix: string;
+        /** Override the design language instruction */
+        designLanguageOverride: string | null;
+        /** Override the output requirements section entirely */
+        outputRequirementsOverride: string[] | null;
+    };
+    /** Validation settings */
+    validation: {
+        /** Treat warnings as errors */
+        strictMode: boolean;
+        /** Disable specific warning checks by ID */
+        suppressedWarnings: string[];
+        /** Auto-inject validation feedback into refinement prompts */
+        autoFeedback: boolean;
+    };
+    /** API server settings (when api mode is enabled) */
+    apiServer: {
+        port: number;
+        host: string;
+    };
+}
+declare function createDefaultSettings(): InjectionSettings;
+/**
+ * Apply injection settings to modify a generated prompt.
+ * Processes suppressions and additions.
+ */
+declare function applySettingsToPrompt(prompt: string, settings: InjectionSettings): string;
+/**
+ * Serialize settings to JSON for persistence (localStorage, file, etc.)
+ */
+declare function serializeSettings(settings: InjectionSettings): string;
+/**
+ * Deserialize settings from JSON, merging with defaults for missing fields.
+ */
+declare function deserializeSettings(json: string): InjectionSettings;
+
+export { type GenerateMobileUIParams, type GenerationResult, type InjectionSettings, type PromptHistoryEntry, type PromptSession, type RefineUIParams, type RefinementResult, type ValidationResult, applySettingsToPrompt, createDefaultSettings, createPromptSession, deserializeSettings, enrichAppDescription, generateMobileUI, refineUI, serializeCompactDLC, serializeDLCForAI, serializeSettings, validateGeneratedUI };