@biela.dev/core 1.7.13 → 1.7.14

package/dist/lite.d.ts

@@ -1,4 +1,518 @@
-export { AdaptiveScaleResult, ButtonName, CustomSVGStore, DeviceCompare, DeviceCompareProps, DeviceErrorBoundary, DeviceFrame, DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, SVGCropArea, SVGOverrideEntry, SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, ScreenPowerState, StatusBarIndicators, UseAdaptiveScaleOptions, UseOrientationResult, VolumeHUD, VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, getCustomSVGStore, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useOrientation, useScreenPower, useVolumeControl } from './index.js';
-import 'react';
-import '@biela.dev/devices';
-import 'react/jsx-runtime';
+import { RefObject, ReactNode, Component, ErrorInfo, CSSProperties, ReactElement } from 'react';
+import { DeviceMeta, DeviceLayoutContract } from '@biela.dev/devices';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Design token dimension math — conversion utilities.
+ * All device dimensions are in logical points (CSS pixels at 1x).
+ */
+/** Convert logical points to physical pixels */
+declare function ptsToPx(pts: number, dpr: number): number;
+/** Convert physical pixels to logical points */
+declare function pxToPts(px: number, dpr: number): number;
+/** Convert points to percentage of a total dimension */
+declare function ptsToPercent(pts: number, total: number): number;
+/** Apply uniform scale factor to any dimension value */
+declare function scaleValue(value: number, scaleFactor: number): number;
+
+/**
+ * Scale Engine Math — mirrors Xcode Simulator "fit to screen" behavior.
+ *
+ * Rules:
+ * 1. Inner content ALWAYS at 1:1 logical point size
+ * 2. Scale derived from available container space, never hardcoded
+ * 3. SVG frame chrome scales WITH content as one atomic unit
+ * 4. Host layout reserves SCALED dimensions
+ * 5. Maximum scale always 1.0 — never larger than the real device
+ */
+/** Discrete scale steps matching Xcode Simulator presets */
+declare const SCALE_STEPS: readonly [0.25, 0.33, 0.5, 0.75, 1];
+/**
+ * Compute the adaptive scale factor for a device in a given container.
+ * Mirrors Xcode "fit to screen" exactly.
+ *
+ * @param deviceWidth  - Logical points width of the device screen
+ * @param deviceHeight - Logical points height of the device screen
+ * @param containerWidth  - Available CSS px width of the host container
+ * @param containerHeight - Available CSS px height of the host container
+ * @param padding    - Breathing room in px (subtracted from each side)
+ * @param maxScale   - Upper cap — never exceed 1.0 (real device size)
+ * @param minScale   - Lower floor — prevent invisibly small render
+ */
+declare function computeAdaptiveScale(deviceWidth: number, deviceHeight: number, containerWidth: number, containerHeight: number, padding?: number, maxScale?: number, minScale?: number): number;
+/**
+ * Snap a raw scale to the nearest discrete step that does not exceed it.
+ * Fixed version: filters steps to only those <= raw, takes max.
+ * Falls back to raw if no step qualifies.
+ */
+declare function snapToStep(raw: number): number;
+/**
+ * Derive host container size from device dimensions + scale.
+ * The host div occupies these dimensions in normal document flow.
+ */
+declare function computeHostSize(deviceWidth: number, deviceHeight: number, scale: number): {
+    width: number;
+    height: number;
+};
+/** Result returned by the scale computation */
+interface AdaptiveScaleResult {
+    /** Computed scale factor e.g. 0.735 */
+    scale: number;
+    /** Host container width = deviceWidth * scale */
+    scaledWidth: number;
+    /** Host container height = deviceHeight * scale */
+    scaledHeight: number;
+    /** Raw logical pts — scaler div width */
+    deviceWidth: number;
+    /** Raw logical pts — scaler div height */
+    deviceHeight: number;
+    /** True when scale === maxScale (showing at real size) */
+    isAtMaxScale: boolean;
+    /** True when scale < maxScale (container is limiting) */
+    isConstrained: boolean;
+    /** Display string e.g. "73%" */
+    scalePercent: string;
+}
+/**
+ * Full scale computation returning all derived values.
+ */
+declare function computeFullScale(deviceWidth: number, deviceHeight: number, containerWidth: number, containerHeight: number, options?: {
+    padding?: number;
+    maxScale?: number;
+    minScale?: number;
+    snapToSteps?: boolean;
+}): AdaptiveScaleResult;
+
+interface ContainerSize {
+    width: number;
+    height: number;
+}
+/**
+ * Observes an element's content box dimensions via ResizeObserver.
+ * Foundation of adaptive scaling — same mechanism as Xcode's window resize detection.
+ *
+ * Safety features:
+ * 1. Clamps reported size to the visual viewport so a mis-sized parent
+ *    can never cause the device frame to render larger than the screen.
+ * 2. When the element has 0 height (common AI-generated code mistake:
+ *    height: auto or height: 100% without explicit ancestor height),
+ *    uses a viewport-based fallback so the device still renders.
+ * 3. Listens for window resize to stay in sync.
+ */
+declare function useContainerSize(ref: RefObject<HTMLElement | null>): ContainerSize;
+
+interface UseAdaptiveScaleOptions {
+    /** Device metadata (screen dimensions) */
+    device: DeviceMeta;
+    /** Container width from useContainerSize */
+    containerWidth: number;
+    /** Container height from useContainerSize */
+    containerHeight: number;
+    /** Breathing room in px (default: 24) */
+    padding?: number;
+    /** Upper cap — never exceed 1.0 (default: 1.0) */
+    maxScale?: number;
+    /** Lower floor (default: 0.1) */
+    minScale?: number;
+    /** Snap to discrete 25/33/50/75/100% steps (default: false) */
+    snapToSteps?: boolean;
+}
+/**
+ * Full adaptive scale hook — mirrors Xcode "fit to screen".
+ * Recalculates live as container resizes via ResizeObserver.
+ */
+declare function useAdaptiveScale(options: UseAdaptiveScaleOptions): AdaptiveScaleResult;
+
+interface UseDeviceContractResult {
+    contract: DeviceLayoutContract;
+    cssVariables: DeviceLayoutContract["cssVariables"];
+    contentZone: DeviceLayoutContract["contentZone"]["portrait"];
+}
+/**
+ * Hook to access the Device Layout Contract for a given device.
+ * Returns the contract, CSS variables, and content zone for the current orientation.
+ */
+declare function useDeviceContract(deviceId: string, orientation?: "portrait" | "landscape"): UseDeviceContractResult;
+
+interface VolumeState {
+    /** Current volume level 0–1 (16 steps, each = 1/16) */
+    level: number;
+    /** Is audio muted? */
+    muted: boolean;
+    /** Should the HUD be visible? */
+    hudVisible: boolean;
+    /** Increase volume by one step */
+    volumeUp: () => void;
+    /** Decrease volume by one step */
+    volumeDown: () => void;
+    /** Toggle mute */
+    toggleMute: () => void;
+}
+/**
+ * Volume control hook — 16-step volume with auto-hiding HUD.
+ * Applies volume to all <audio> and <video> elements inside `.bielaframe-content`.
+ */
+declare function useVolumeControl(initialVolume?: number): VolumeState;
+
+interface ScreenPowerState {
+    /** Is the screen off? */
+    isOff: boolean;
+    /** Toggle screen on/off */
+    toggle: () => void;
+}
+/**
+ * Screen power hook — manages on/off state for the power button.
+ */
+declare function useScreenPower(): ScreenPowerState;
+
+interface UseOrientationResult {
+    /** Current orientation */
+    orientation: "portrait" | "landscape";
+    /** Convenience boolean */
+    isLandscape: boolean;
+    /** Toggle between portrait and landscape */
+    toggle: () => void;
+    /** Set orientation directly */
+    setOrientation: (o: "portrait" | "landscape") => void;
+}
+/**
+ * Hook for managing device orientation state with a toggle function.
+ *
+ * ```tsx
+ * const { orientation, toggle } = useOrientation();
+ * <button onClick={toggle}>Rotate</button>
+ * <DeviceFrame deviceId="iphone-17-pro" orientation={orientation} />
+ * ```
+ */
+declare function useOrientation(initial?: "portrait" | "landscape"): UseOrientationResult;
+
+/**
+ * Resolve device SVG component by ID.
+ * This is a lookup registry — devices register their SVG components here.
+ */
+type DeviceSVGComponent = React.ComponentType<{
+    colorScheme?: "light" | "dark";
+    style?: React.CSSProperties;
+}>;
+interface FrameInfo {
+    bezelTop: number;
+    bezelBottom: number;
+    bezelLeft: number;
+    bezelRight: number;
+    totalWidth: number;
+    totalHeight: number;
+    screenWidth: number;
+    screenHeight: number;
+    screenRadius: number;
+}
+/** Register a device SVG component for use with DeviceFrame */
+declare function registerDeviceSVG(deviceId: string, component: DeviceSVGComponent, frame: FrameInfo): void;
+/** Optional crop area to rewrite the SVG viewBox (e.g., to exclude side buttons) */
+interface SVGCropArea {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Screen rectangle in SVG native coordinates — used to punch a transparent hole */
+interface SVGScreenRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx?: number;
+}
+/**
+ * Register a custom device SVG from a raw SVG string.
+ *
+ * Creates a React component that renders the SVG with scoped IDs
+ * and registers it in the SVG_REGISTRY.
+ *
+ * The inner <svg> element is rewritten to use width="100%" height="100%"
+ * so it fills the parent container (which is sized by the frame info).
+ *
+ * If `cropViewBox` is provided, the SVG viewBox is set to that area,
+ * cropping out external elements like side buttons.
+ *
+ * If `screenRect` is provided, a mask is injected to punch a transparent
+ * hole where the screen is, so content underneath shows through.
+ */
+declare function registerCustomDeviceSVG(deviceId: string, svgString: string, frame: FrameInfo, cropViewBox?: SVGCropArea, screenRect?: SVGScreenRect): void;
+interface DeviceFrameProps {
+    /** Device ID e.g. "iphone-16-pro" */
+    device?: string;
+    /** Alias for device — accepts either prop name */
+    deviceId?: string;
+    /** Orientation */
+    orientation?: "portrait" | "landscape";
+    /** Scale mode: "fit" auto-scales, "manual" uses manualScale value */
+    scaleMode?: "fit" | "manual" | "steps";
+    /** Manual scale override (0.1–1.0), only when scaleMode="manual" */
+    manualScale?: number;
+    /** Show safe zone overlay (dev tool) */
+    showSafeAreaOverlay?: boolean;
+    /** Show DLC JSON panel */
+    showDLCPanel?: boolean;
+    /** Show scale bar (default: true) */
+    showScaleBar?: boolean;
+    /** Frame color scheme */
+    colorScheme?: "light" | "dark";
+    /** Callback when DLC is ready */
+    onContractReady?: (dlc: DeviceLayoutContract) => void;
+    /** Callback when scale changes */
+    onScaleChange?: (scale: number) => void;
+    /** Content rendered inside the device screen at real resolution */
+    children?: ReactNode;
+}
+/**
+ * DeviceFrame — the main BielaFrame component.
+ *
+ * Implements the Two-World Rendering Model:
+ * - Inner content renders at 1:1 device resolution (e.g. 402×874px)
+ * - Visual presentation scales via CSS transform: scale()
+ * - The AI component always thinks it's on a real device
+ *
+ * DOM structure:
+ *   bielaframe-sentinel (fills parent, ResizeObserver target)
+ *     └── bielaframe-host (scaled dimensions in flow)
+ *           └── bielaframe-scaler (real device dims, transform: scale(N))
+ *                 ├── bielaframe-content (clipped to screen, CSS vars injected)
+ *                 │     └── children (AI-generated component)
+ *                 ├── SVG frame overlay (pointer-events: none)
+ *                 └── SafeAreaOverlay (optional dev tool)
+ *           └── ScaleBar (outside scaler, in normal flow)
+ */
+declare function DeviceFrame({ device: deviceProp, deviceId, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, colorScheme, onContractReady, onScaleChange, children, }: DeviceFrameProps): react_jsx_runtime.JSX.Element;
+
+interface DeviceCompareProps {
+    /** First device ID */
+    deviceA: string;
+    /** Second device ID */
+    deviceB: string;
+    /** Orientation for both devices */
+    orientation?: "portrait" | "landscape";
+    /** Frame color scheme */
+    colorScheme?: "light" | "dark";
+    /** Show safe area overlays */
+    showSafeAreaOverlay?: boolean;
+    /** Show scale bars */
+    showScaleBar?: boolean;
+    /** Layout direction — "auto" picks row for portrait, column for landscape */
+    layout?: "horizontal" | "vertical" | "auto";
+    /** Gap between the two frames in px (default: 24) */
+    gap?: number;
+    /** Content rendered inside BOTH device frames */
+    children?: ReactNode;
+    /** Content for device A only (overrides children for A) */
+    childrenA?: ReactNode;
+    /** Content for device B only (overrides children for B) */
+    childrenB?: ReactNode;
+    /** Callback when device A contract is ready */
+    onContractReadyA?: (dlc: DeviceLayoutContract) => void;
+    /** Callback when device B contract is ready */
+    onContractReadyB?: (dlc: DeviceLayoutContract) => void;
+}
+/**
+ * DeviceCompare — renders two device frames side-by-side for comparison.
+ *
+ * Layout defaults to "auto": horizontal (row) in portrait, vertical (column) in landscape.
+ * Each frame auto-scales independently to fit its half of the container.
+ *
+ * Must be placed inside a container with explicit width and height.
+ */
+declare function DeviceCompare({ deviceA, deviceB, orientation, colorScheme, showSafeAreaOverlay, showScaleBar, layout, gap, children, childrenA, childrenB, onContractReadyA, onContractReadyB, }: DeviceCompareProps): react_jsx_runtime.JSX.Element;
+
+interface Props {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error Boundary wrapping the children slot in DeviceFrame.
+ * AI-generated components will crash — this catches them gracefully
+ * and renders a fallback inside the device screen area.
+ */
+declare class DeviceErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+interface SafeAreaViewProps {
+    /** Which edges to apply safe area padding to (default: all) */
+    edges?: Array<"top" | "bottom" | "left" | "right">;
+    children: ReactNode;
+    style?: CSSProperties;
+}
+/**
+ * Convenience wrapper that applies safe area padding via CSS variables.
+ * Uses var(--safe-top), var(--safe-bottom), etc. — injected by DeviceFrame.
+ *
+ * Usage inside a generated app:
+ *   <SafeAreaView edges={["top", "bottom"]}>
+ *     {content that never overlaps hardware elements}
+ *   </SafeAreaView>
+ */
+declare function SafeAreaView({ edges, children, style }: SafeAreaViewProps): react_jsx_runtime.JSX.Element;
+
+interface SafeAreaOverlayProps {
+    contract: DeviceLayoutContract;
+    orientation: "portrait" | "landscape";
+}
+/**
+ * Dev overlay showing safe zones when showSafeAreaOverlay={true}.
+ * Does NOT affect layout — position: absolute, pointerEvents: none.
+ *
+ * Colors:
+ * - Red: status bar zone + home indicator zone (restricted)
+ * - Orange: hardware overlay (Dynamic Island / punch-hole)
+ * - Green: content zone (usable area)
+ * - White dimension labels at each edge
+ */
+declare function SafeAreaOverlay({ contract, orientation }: SafeAreaOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface ScaleBarProps {
+    deviceName: string;
+    deviceWidth: number;
+    deviceHeight: number;
+    scale: number;
+    scalePercent: string;
+    isAtMaxScale: boolean;
+    isConstrained: boolean;
+    onScaleChange?: (scale: number) => void;
+    onFit?: () => void;
+    onRealSize?: () => void;
+}
+/**
+ * Persistent footer below device showing scale state:
+ * [ iPhone 16 Pro · 402×874pt | ━━━●━━━━━ 66% | Fit ↗ | 1:1 ]
+ *
+ * Accessibility:
+ * - role="slider" with aria-valuenow on scrubber
+ * - aria-label on the component
+ * - aria-live="polite" on scale announcements
+ */
+declare function ScaleBar({ deviceName, deviceWidth, deviceHeight, scale, scalePercent, isAtMaxScale, isConstrained, onScaleChange, onFit, onRealSize, }: ScaleBarProps): react_jsx_runtime.JSX.Element;
+
+interface VolumeHUDProps {
+    level: number;
+    muted: boolean;
+    visible: boolean;
+    platform: "ios" | "android";
+}
+/**
+ * Volume HUD overlay — iOS-style vertical pill or Android-style horizontal bar.
+ */
+declare function VolumeHUD({ level, muted, visible, platform }: VolumeHUDProps): react_jsx_runtime.JSX.Element;
+
+type ButtonName = "volumeUp" | "volumeDown" | "power" | "actionButton" | "cameraControl";
+interface HardwareButtonsProps {
+    /** The container element that holds the SVG frame overlay */
+    frameContainerRef: React.RefObject<HTMLDivElement | null>;
+    /** Callbacks for button actions */
+    onButtonPress?: (button: ButtonName) => void;
+    /** Whether interactive buttons are enabled */
+    enabled?: boolean;
+    /** Current orientation — triggers button position re-discovery */
+    orientation?: "portrait" | "landscape";
+}
+/**
+ * HardwareButtons — creates invisible click-target overlays positioned
+ * over the SVG button elements.
+ *
+ * Because the SVG frame overlay has pointer-events: none (so content
+ * underneath remains interactive), we can't attach event listeners directly
+ * to SVG elements. Instead, we:
+ *   1. Find all [data-button] elements in the SVG
+ *   2. Read their bounding rects relative to the scaler container
+ *   3. Render transparent absolutely-positioned divs at those positions
+ *   4. Handle mouse/touch events on those divs
+ *   5. Apply press animation to the original SVG elements
+ */
+declare function HardwareButtons({ frameContainerRef, onButtonPress, enabled, orientation, }: HardwareButtonsProps): ReactElement | null;
+
+interface DynamicStatusBarProps {
+    contract: DeviceLayoutContract;
+    orientation: "portrait" | "landscape";
+    colorScheme: "light" | "dark";
+    /** Show a live updating clock (default: true) */
+    showLiveClock?: boolean;
+    /** Fixed time string override (e.g. "9:41") — disables live clock */
+    fixedTime?: string;
+}
+/**
+ * DynamicStatusBar — renders ONLY a live clock overlay.
+ *
+ * The SVG frame already provides all decorative status bar elements
+ * (signal bars, wifi, battery). This component only replaces the
+ * static time text (e.g. "9:41") with a live-updating clock.
+ *
+ * It renders a small opaque patch behind the clock text so the
+ * SVG's baked-in static time is fully covered, then draws the
+ * live time on top.
+ *
+ * Platform-specific clock positions:
+ * - iOS Dynamic Island: left side, paddingLeft ~20
+ * - iOS Notch: left side, paddingLeft ~20
+ * - iOS SE: centered
+ * - Android: left side, paddingLeft ~16
+ */
+declare function DynamicStatusBar({ contract, orientation, colorScheme, showLiveClock, fixedTime, }: DynamicStatusBarProps): react_jsx_runtime.JSX.Element | null;
+
+interface StatusBarIndicatorsProps {
+    platform: "ios" | "android";
+    colorScheme: "light" | "dark";
+}
+/**
+ * Static decorative status bar indicators — signal, wifi, battery.
+ * Rendered as small inline SVGs, platform-specific styling.
+ */
+declare function StatusBarIndicators({ platform, colorScheme }: StatusBarIndicatorsProps): react_jsx_runtime.JSX.Element;
+
+interface SVGOverrideEntry {
+    deviceId: string;
+    svgString: string;
+    bezelTop: number;
+    bezelBottom: number;
+    bezelLeft: number;
+    bezelRight: number;
+    screenRect?: SVGScreenRect;
+    updatedAt: string;
+}
+/**
+ * Persistent storage for custom SVG overrides.
+ *
+ * When a user uploads a custom SVG frame for a device, it's stored in
+ * localStorage and automatically applied on subsequent imports.
+ *
+ * SSR-safe: falls back to no-op storage when localStorage is unavailable.
+ */
+declare class CustomSVGStore {
+    private storage;
+    constructor(storage?: Storage | null);
+    /** Load all stored overrides */
+    getAll(): Record<string, SVGOverrideEntry>;
+    /** Save an override and register it in the SVG registry */
+    save(entry: SVGOverrideEntry): void;
+    /** Remove an override (revert to built-in) */
+    remove(deviceId: string): void;
+    /** Check if a device has a custom override */
+    has(deviceId: string): boolean;
+    /** Get a single override by device ID */
+    get(deviceId: string): SVGOverrideEntry | undefined;
+    /**
+     * Apply all stored overrides to the SVG registry.
+     * Called during auto-registration to restore user customizations.
+     */
+    applyAll(): void;
+    private applyEntry;
+    private persist;
+}
+/** Get the default CustomSVGStore instance (singleton, uses localStorage) */
+declare function getCustomSVGStore(): CustomSVGStore;
+
+export { type AdaptiveScaleResult, type ButtonName, CustomSVGStore, DeviceCompare, type DeviceCompareProps, DeviceErrorBoundary, DeviceFrame, type DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGOverrideEntry, type SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, type UseOrientationResult, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, getCustomSVGStore, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useOrientation, useScreenPower, useVolumeControl };

package/dist/lite.js

@@ -818,6 +818,7 @@ function DeviceFrame({
                         overflow: "hidden",
                         backfaceVisibility: "hidden",
                         transform: "translateZ(0)",
+                        zIndex: 12,
                         ...cssVarStyle
                       },
                       children: /* @__PURE__ */ jsx(DeviceErrorBoundary, { children })