@biela.dev/devices 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,311 @@
+import { D as DeviceMeta, a as DeviceLayoutData, b as DeviceLayoutContract, S as SafeAreaInsets, C as ContentRect, H as HardwareOverlayType, O as OverlayRect, R as RegisteredDevice } from './contract-types-Cw1rmF3b.js';
+export { c as DeviceCSSVariables, d as DeviceFrameInfo, e as SVGCropRect, f as SVGScreenRect } from './contract-types-Cw1rmF3b.js';
+export { IPHONE_16E_FRAME, IPHONE_16E_LAYOUT, IPHONE_16E_META, IPHONE_16_FRAME, IPHONE_16_LAYOUT, IPHONE_16_META, IPHONE_17_PRO_FRAME, IPHONE_17_PRO_LAYOUT, IPHONE_17_PRO_MAX_FRAME, IPHONE_17_PRO_MAX_LAYOUT, IPHONE_17_PRO_MAX_META, IPHONE_17_PRO_META, IPHONE_AIR_FRAME, IPHONE_AIR_LAYOUT, IPHONE_AIR_META, IPHONE_SE_3_FRAME, IPHONE_SE_3_LAYOUT, IPHONE_SE_3_META, IPhone16SVG, IPhone16eSVG, IPhone17ProMaxSVG, IPhone17ProSVG, IPhoneAirSVG, IPhoneSE3SVG } from './ios/index.js';
+export { GALAXY_S25_EDGE_FRAME, GALAXY_S25_EDGE_LAYOUT, GALAXY_S25_EDGE_META, GALAXY_S25_FRAME, GALAXY_S25_LAYOUT, GALAXY_S25_META, GALAXY_S25_ULTRA_FRAME, GALAXY_S25_ULTRA_LAYOUT, GALAXY_S25_ULTRA_META, GalaxyS25EdgeSVG, GalaxyS25SVG, GalaxyS25UltraSVG, PIXEL_9_PRO_FRAME, PIXEL_9_PRO_LAYOUT, PIXEL_9_PRO_META, PIXEL_9_PRO_XL_FRAME, PIXEL_9_PRO_XL_LAYOUT, PIXEL_9_PRO_XL_META, Pixel9ProSVG, Pixel9ProXLSVG } from './android/index.js';
+import 'react/jsx-runtime';
+
+/**
+ * Built-in device metadata registry — 11 devices.
+ *
+ * Curated to cover every unique screen class (logical resolution).
+ * Duplicate resolutions across generations are represented by the latest model.
+ *
+ * ALL DIMENSIONS VERIFIED:
+ *
+ * iPhone 17 Pro Max:  440×956pt @3x  (covers iPhone 16 Pro Max)
+ * iPhone 17 Pro:      402×874pt @3x  (covers iPhone 16 Pro, iPhone 17)
+ * iPhone Air:         420×912pt @3x  (unique new size class)
+ * iPhone 16:          393×852pt @3x  (base Dynamic Island)
+ * iPhone 16e:         390×844pt @3x  (notch, unique width)
+ * iPhone SE 3:        375×667pt @2x  (legacy home-button form factor)
+ * Galaxy S25 Ultra:   384×824dp @3.75x (covers S24 Ultra)
+ * Galaxy S25:         360×780dp @3x  (covers S24)
+ * Galaxy S25 Edge:    382×824dp @3.75x (unique narrow form factor)
+ * Pixel 9 Pro:        393×851dp @3x  (covers Pixel 9, S25+)
+ * Pixel 9 Pro XL:     448×968dp @3x  (largest Android)
+ */
+declare const BUILTIN_DEVICES: Record<string, DeviceMeta>;
+declare const DEVICE_LAYOUTS: Record<string, DeviceLayoutData>;
+/**
+ * Look up device metadata — checks built-in first, then custom registry.
+ */
+declare function getDeviceMetadata(deviceId: string): DeviceMeta;
+/**
+ * Get all device IDs — built-in + custom.
+ */
+declare function getAllDeviceIds(): string[];
+
+/** Derive the content zone from screen dimensions and safe area insets */
+declare function deriveContentZone(screenWidth: number, screenHeight: number, safeArea: SafeAreaInsets): ContentRect;
+/** Build CSS variables from device data at REAL unscaled values */
+declare function buildCSSVariables(screen: DeviceMeta["screen"], safeArea: SafeAreaInsets, statusBar: DeviceLayoutContract["statusBar"], homeIndicator: DeviceLayoutContract["homeIndicator"], hardwareOverlays: DeviceLayoutContract["hardwareOverlays"]): DeviceLayoutContract["cssVariables"];
+/** Build the human-readable AI prompt constraints string */
+declare function buildAIPromptConstraints(contract: Omit<DeviceLayoutContract, "aiPromptConstraints">): string;
+/**
+ * Get the full Device Layout Contract for a device.
+ * This is the single source of truth that feeds both CSS variables and AI prompts.
+ */
+declare function getDeviceContract(deviceId: string, orientation?: "portrait" | "landscape"): DeviceLayoutContract;
+
+/**
+ * Extract the native coordinate space from an SVG string.
+ *
+ * Priority: viewBox → width/height attributes → fallback (390×844).
+ * This tells us what coordinate space the SVG was authored in,
+ * which may differ from the device's logical point dimensions.
+ */
+interface SVGNativeDimensions {
+    width: number;
+    height: number;
+    hasViewBox: boolean;
+    source: "viewBox" | "widthHeight" | "fallback";
+}
+declare function parseSVGNativeDimensions(svgString: string): SVGNativeDimensions;
+
+/**
+ * Normalize an SVG to the canonical logical-point coordinate space.
+ *
+ * Takes an SVG that may be authored at physical pixels (e.g., 1206×2622 for iPhone 16 Pro at 3x)
+ * and rewrites it to logical points (402×874). Also rescales all data-zone element coordinates.
+ */
+interface NormalizationResult {
+    normalizedSVG: string;
+    scaleFactors: {
+        x: number;
+        y: number;
+    };
+    aspectRatioWarning: string | null;
+    wasAlreadyNormalized: boolean;
+    nativeDimensions: {
+        width: number;
+        height: number;
+    };
+}
+declare function normalizeSVGToLogicalPoints(svgString: string, targetWidth: number, targetHeight: number): NormalizationResult;
+
+/**
+ * Parse an SVG with data-zone annotations into a DeviceLayoutContract.
+ *
+ * Reads `data-zone` attributes on SVG elements to extract:
+ * - screen-area → screen dimensions
+ * - safe-area-top / safe-area-bottom → safe area insets
+ * - hardware-overlay → Dynamic Island / notch / punch-hole rect
+ * - status-bar → status bar zone
+ * - home-indicator → home indicator zone
+ */
+
+interface ParsedZone {
+    zone: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Extract all data-zone elements and their bounding attributes from SVG markup.
+ */
+declare function extractZones(svgString: string): ParsedZone[];
+interface ParseSVGContractOptions {
+    /** Device metadata (id, name, platform, year, screen info) */
+    meta: DeviceMeta;
+    /** Hardware overlay type if known */
+    overlayType?: HardwareOverlayType;
+    /** Override overlay shape */
+    overlayShape?: OverlayRect["shape"];
+    /** Status bar style override */
+    statusBarStyle?: DeviceLayoutContract["statusBar"]["style"];
+    /** Home indicator type override */
+    homeIndicatorType?: DeviceLayoutContract["homeIndicator"]["type"];
+}
+/**
+ * Build a full DeviceLayoutContract from a normalized SVG with data-zone annotations.
+ */
+declare function parseSVGToContract(normalizedSVG: string, options: ParseSVGContractOptions): DeviceLayoutContract;
+
+/**
+ * Pre-registration validation for normalized SVGs.
+ *
+ * Checks that the normalization result is sane before registering a custom device.
+ */
+
+interface ValidationResult {
+    passed: boolean;
+    warnings: string[];
+    errors: string[];
+}
+/**
+ * Validate a normalized SVG before registration.
+ */
+declare function validateNormalizedSVG(result: NormalizationResult, targetWidth: number, targetHeight: number): ValidationResult;
+
+/**
+ * Scope all SVG IDs to a device-specific prefix to prevent collisions
+ * when multiple device frames are rendered on the same page.
+ *
+ * Rewrites:
+ * - id="foo" → id="deviceId__foo"
+ * - url(#foo) → url(#deviceId__foo)
+ * - href="#foo" → href="#deviceId__foo"
+ * - xlink:href="#foo" → xlink:href="#deviceId__foo"
+ */
+declare function scopeSVGIds(svgString: string, deviceId: string): string;
+
+/**
+ * Auto-detect device zones from SVG structure.
+ *
+ * Two-pass approach:
+ * 1. Name-based: scan element IDs/classes/data-attributes for known keywords
+ * 2. Geometric heuristics: analyze ALL rects by size, position, fill, and corner radius
+ *    to identify screen area, dynamic island, phone body, and side buttons
+ *
+ * The geometric pass is critical for real-world Figma SVGs that use auto-generated
+ * IDs like "clip0_44_55" with no semantic naming.
+ */
+interface DetectedZone {
+    id: string;
+    /** The zone type we inferred */
+    type: ZoneType;
+    /** The SVG element's original id/name that matched */
+    sourceLabel: string;
+    /** Which keyword matched */
+    matchedKeyword: string;
+    /** Confidence: "high" for exact keyword match, "medium" for partial */
+    confidence: "high" | "medium";
+    /** Bounding box in SVG coordinate space */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Corner radius (from SVG rx attribute), only for screen-area zones */
+    rx?: number;
+}
+type ZoneType = "screen-area" | "hardware-overlay" | "safe-area-top" | "safe-area-bottom" | "safe-area-left" | "safe-area-right" | "status-bar" | "home-indicator" | "hardware-button";
+/**
+ * Result of analyzing the SVG geometry — includes both zones and structural info.
+ */
+interface SVGAnalysis {
+    /** Detected zones for the Zone Tagger */
+    zones: DetectedZone[];
+    /** Phone body bounding rect (largest rounded rect), if found */
+    phoneBody: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        rx: number;
+    } | null;
+    /** Rects identified as external side buttons */
+    sideButtons: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }[];
+    /** All extracted rects for debugging */
+    allRects: RectInfo[];
+}
+/** Internal rect representation with fill/rx info */
+interface RectInfo {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx: number;
+    fill: string | null;
+    id: string | null;
+}
+/**
+ * Auto-detect zones using both name-based and geometric approaches.
+ * Falls back to geometric heuristics when name-based detection finds nothing.
+ */
+declare function autoDetectZones(svgString: string): DetectedZone[];
+/**
+ * Full SVG analysis — returns zones plus structural info (phone body, side buttons).
+ * Used by the Registration Wizard for bezel calculation and button handling.
+ */
+declare function analyzeSVGGeometry(svgString: string): SVGAnalysis;
+/**
+ * Classify detected side buttons into specific hardware button types.
+ *
+ * Classification strategy based on real device button placement:
+ * - LEFT side (iOS): action button (top), volume up (middle-top), volume down (middle-bottom)
+ * - LEFT side (Android): volume up (top), volume down (bottom)
+ * - RIGHT side: power button (top/middle), camera control (lower, if present)
+ *
+ * Uses vertical position and size to distinguish buttons.
+ */
+interface ClassifiedButton {
+    type: "volume-up" | "volume-down" | "power" | "action" | "camera";
+    side: "left" | "right";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+declare function classifySideButtons(sideButtons: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}[], phoneBody: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null): ClassifiedButton[];
+/**
+ * Get a list of all identifiable SVG element names for UI display.
+ */
+declare function listSVGLayerNames(svgString: string): {
+    tag: string;
+    name: string;
+}[];
+
+/**
+ * Custom device registry — stores user-imported devices in localStorage.
+ *
+ * Provides CRUD operations for custom devices, persistence, and export/import.
+ * Custom devices are stored alongside built-in devices but tracked separately.
+ */
+
+declare class DeviceRegistry {
+    private devices;
+    private storage;
+    constructor(storage?: Storage | null);
+    /** Register or update a custom device */
+    register(device: RegisteredDevice): void;
+    /** Get a custom device by ID */
+    get(deviceId: string): RegisteredDevice | undefined;
+    /** Get the metadata for a custom device */
+    getMeta(deviceId: string): DeviceMeta | undefined;
+    /** Get the contract for a custom device */
+    getContract(deviceId: string): DeviceLayoutContract | undefined;
+    /** List all custom devices */
+    list(): RegisteredDevice[];
+    /** List all custom device IDs */
+    listIds(): string[];
+    /** Check if a custom device exists */
+    has(deviceId: string): boolean;
+    /** Remove a custom device */
+    remove(deviceId: string): boolean;
+    /** Remove all custom devices */
+    clear(): void;
+    /** Get the number of custom devices */
+    get size(): number;
+    /** Export all custom devices as a JSON string */
+    exportAll(): string;
+    /** Import custom devices from a JSON string (merges with existing) */
+    importAll(json: string): {
+        imported: number;
+        skipped: string[];
+    };
+    /** Import and overwrite existing entries */
+    importAllOverwrite(json: string): number;
+    private load;
+    private save;
+}
+declare function getDeviceRegistry(): DeviceRegistry;
+/** Reset the singleton (for testing) */
+declare function resetDeviceRegistry(): void;
+
+export { BUILTIN_DEVICES, type ClassifiedButton, ContentRect, DEVICE_LAYOUTS, type DetectedZone, DeviceLayoutContract, DeviceLayoutData, DeviceMeta, DeviceRegistry, HardwareOverlayType, type NormalizationResult, OverlayRect, type ParseSVGContractOptions, type ParsedZone, RegisteredDevice, type SVGAnalysis, type SVGNativeDimensions, SafeAreaInsets, type ValidationResult, type ZoneType, analyzeSVGGeometry, autoDetectZones, buildAIPromptConstraints, buildCSSVariables, classifySideButtons, deriveContentZone, extractZones, getAllDeviceIds, getDeviceContract, getDeviceMetadata, getDeviceRegistry, listSVGLayerNames, normalizeSVGToLogicalPoints, parseSVGNativeDimensions, parseSVGToContract, resetDeviceRegistry, scopeSVGIds, validateNormalizedSVG };