@biela.dev/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,408 @@
+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.
+ * Uses the actual canvas div, not the window, so it's panel-independent.
+ */
+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;
+
+/**
+ * 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;
+    /** 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, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, colorScheme, onContractReady, onScaleChange, children, }: DeviceFrameProps): 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;
+
+export { type AdaptiveScaleResult, type ButtonName, DeviceErrorBoundary, DeviceFrame, type DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useScreenPower, useVolumeControl };