@pushframe/sdk 0.1.5 → 0.1.9

package/src/transformer/index.ts

@@ -0,0 +1,1016 @@
+/**
+ * Craft.js → PushFrame SDUI transformer
+ *
+ * Converts a Craft.js editor schema (produced by the dashboard) into the
+ * SDUINode tree consumed by the SDK's RecursiveRenderer at runtime.
+ *
+ * This module is intended for use by the backend/service layer or the
+ * dashboard — it is NOT executed inside the React Native app at runtime.
+ */
+
+import type { Action, SchemaNode } from '../context/PushFrameContext';
+
+// ─── Craft input types ────────────────────────────────────────────────────────
+
+export type CraftNode = {
+    type: { resolvedName: string };
+    props?: Record<string, unknown>;
+    nodes?: string[];
+    parent?: string;
+};
+
+export type CraftSchema = Record<string, CraftNode>;
+
+// ─── Output types ─────────────────────────────────────────────────────────────
+
+type SpacingValue = number | { top?: number; right?: number; bottom?: number; left?: number };
+type RadiusValue  = number | { tl?: number; tr?: number; br?: number; bl?: number };
+type SizeModeValue = 'fill' | 'hug' | number;
+
+interface ShadowValue {
+    color: string;
+    offsetX: number;
+    offsetY: number;
+    blur: number;
+    /** 0–1 */
+    opacity: number;
+}
+
+interface BorderValue {
+    width?: number;
+    color?: string;
+    style?: 'solid' | 'dotted' | 'dashed';
+    widths?: { top?: number; right?: number; bottom?: number; left?: number };
+}
+
+interface SafeAreaValue {
+    top?: boolean;
+    right?: boolean;
+    bottom?: boolean;
+    left?: boolean;
+}
+
+/**
+ * The SDUI node shape produced by this transformer and consumed by the SDK's
+ * RecursiveRenderer. Aligned with `SchemaNode` from the SDK context.
+ */
+export interface SDUINode extends SchemaNode {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    children?: SDUINode[];
+    /** FlatList per-item render template. */
+    itemTemplate?: SDUINode;
+    /** Conditional render expression. Falsy → node is hidden. */
+    if?: unknown;
+    actions?: Action[];
+}
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const BRIDGE_KEYS = new Set([
+    '_schemaId', '_schemaType', '_schemaActions', '_schemaIf', '_schemaRenderItem',
+]);
+
+const ALIGN_MAP: Record<string, string> = {
+    start:    'flex-start',
+    center:   'center',
+    end:      'flex-end',
+    stretch:  'stretch',
+    baseline: 'baseline',
+};
+
+const DISTRIBUTE_MAP: Record<string, string> = {
+    start:           'flex-start',
+    center:          'center',
+    end:             'flex-end',
+    'space-between': 'space-between',
+    'space-around':  'space-around',
+    'space-evenly':  'space-evenly',
+};
+
+const FIT_TO_RESIZE_MODE: Record<string, string> = {
+    cover:   'cover',
+    contain: 'contain',
+    fill:    'stretch', // RN uses 'stretch', not 'fill'
+    center:  'center',
+};
+
+const FONT_WEIGHT_MAP: Record<string, string> = {
+    regular:  '400',
+    medium:   '500',
+    semibold: '600',
+    bold:     '700',
+};
+
+const TEXT_STYLE_PRESETS: Record<string, {
+    fontSize: number;
+    fontWeight: string;
+    lineHeight?: number;
+    textTransform?: string;
+    letterSpacing?: number;
+}> = {
+    'heading-1': { fontSize: 28, fontWeight: '700' },
+    'heading-2': { fontSize: 22, fontWeight: '700' },
+    'heading-3': { fontSize: 18, fontWeight: '600' },
+    'body':      { fontSize: 16, fontWeight: '400' },
+    'body-sm':   { fontSize: 14, fontWeight: '400' },
+    'caption':   { fontSize: 12, fontWeight: '400' },
+    'label':     { fontSize: 13, fontWeight: '500' },
+    'overline':  { fontSize: 11, fontWeight: '500', textTransform: 'uppercase', letterSpacing: 0.8 },
+};
+
+// inputType → RN keyboard + behaviour props
+const INPUT_TYPE_MAP: Record<string, {
+    keyboardType: string;
+    secureTextEntry: boolean;
+    autoCapitalize: string;
+    autoCorrect: boolean;
+}> = {
+    text:     { keyboardType: 'default',       secureTextEntry: false, autoCapitalize: 'sentences', autoCorrect: true  },
+    email:    { keyboardType: 'email-address', secureTextEntry: false, autoCapitalize: 'none',      autoCorrect: false },
+    password: { keyboardType: 'default',       secureTextEntry: true,  autoCapitalize: 'none',      autoCorrect: false },
+    number:   { keyboardType: 'numeric',       secureTextEntry: false, autoCapitalize: 'none',      autoCorrect: false },
+    decimal:  { keyboardType: 'decimal-pad',   secureTextEntry: false, autoCapitalize: 'none',      autoCorrect: false },
+    phone:    { keyboardType: 'phone-pad',     secureTextEntry: false, autoCapitalize: 'none',      autoCorrect: false },
+    url:      { keyboardType: 'url',           secureTextEntry: false, autoCapitalize: 'none',      autoCorrect: false },
+    search:   { keyboardType: 'default',       secureTextEntry: false, autoCapitalize: 'none',      autoCorrect: false },
+};
+
+// ─── Prop helpers ─────────────────────────────────────────────────────────────
+
+function stripBridgeKeys(props: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const k in props) {
+        if (!BRIDGE_KEYS.has(k)) out[k] = props[k];
+    }
+    return out;
+}
+
+function extractMeta(raw: Record<string, unknown>): {
+    actions: Action[] | undefined;
+    condition: unknown;
+} {
+    return {
+        actions:   raw._schemaActions as Action[] | undefined,
+        condition: raw._schemaIf,
+    };
+}
+
+// ─── RN style sub-builders ────────────────────────────────────────────────────
+
+function resolveSizeModeRN(
+    value: SizeModeValue | undefined,
+    axis: 'width' | 'height',
+    out: Record<string, unknown>,
+    parentDirection: 'vertical' | 'horizontal',
+): void {
+    if (value === undefined) return;
+    if (value === 'fill') {
+        const isMainAxis =
+            (parentDirection === 'vertical'   && axis === 'height') ||
+            (parentDirection === 'horizontal' && axis === 'width');
+        if (isMainAxis) {
+            out.flex = 1;
+        } else {
+            out.alignSelf = 'stretch';
+        }
+    } else if (value === 'hug') {
+        out.alignSelf = 'flex-start';
+    } else {
+        out[axis] = value;
+    }
+}
+
+function resolvePaddingRN(padding: SpacingValue | undefined): Record<string, unknown> {
+    if (padding === undefined) return {};
+    if (typeof padding === 'number') return { padding };
+    const { top, right, bottom, left } = padding;
+    if (top === bottom && left === right && top !== undefined && left !== undefined) {
+        return { paddingVertical: top, paddingHorizontal: left };
+    }
+    return {
+        ...(top    !== undefined ? { paddingTop:    top    } : {}),
+        ...(right  !== undefined ? { paddingRight:  right  } : {}),
+        ...(bottom !== undefined ? { paddingBottom: bottom } : {}),
+        ...(left   !== undefined ? { paddingLeft:   left   } : {}),
+    };
+}
+
+function resolveRadiusRN(radius: RadiusValue | undefined): Record<string, unknown> {
+    if (radius === undefined) return {};
+    if (typeof radius === 'number') return { borderRadius: radius };
+    return {
+        ...(radius.tl !== undefined ? { borderTopLeftRadius:     radius.tl } : {}),
+        ...(radius.tr !== undefined ? { borderTopRightRadius:    radius.tr } : {}),
+        ...(radius.br !== undefined ? { borderBottomRightRadius: radius.br } : {}),
+        ...(radius.bl !== undefined ? { borderBottomLeftRadius:  radius.bl } : {}),
+    };
+}
+
+function resolveBorderRN(border: BorderValue | undefined): Record<string, unknown> {
+    if (!border) return {};
+    const out: Record<string, unknown> = {};
+    if (border.style) out.borderStyle = border.style;
+    if (border.color) out.borderColor = border.color;
+    if (border.widths) {
+        const w = border.widths;
+        if (w.top    !== undefined) out.borderTopWidth    = w.top;
+        if (w.right  !== undefined) out.borderRightWidth  = w.right;
+        if (w.bottom !== undefined) out.borderBottomWidth = w.bottom;
+        if (w.left   !== undefined) out.borderLeftWidth   = w.left;
+    } else if (border.width !== undefined) {
+        out.borderWidth = border.width;
+    }
+    return out;
+}
+
+function resolveShadowRN(shadow: ShadowValue | undefined): Record<string, unknown> {
+    if (!shadow) return {};
+    return {
+        shadowColor:   shadow.color,
+        shadowOffset:  { width: shadow.offsetX, height: shadow.offsetY },
+        shadowRadius:  shadow.blur,
+        shadowOpacity: shadow.opacity,
+        elevation:     Math.round(shadow.blur / 2),
+    };
+}
+
+function resolveTransformRN(props: {
+    rotate?: number;
+    scale?: number;
+    translateX?: number;
+    translateY?: number;
+}): Record<string, unknown> {
+    const transforms: Record<string, unknown>[] = [];
+    if (props.rotate     !== undefined && props.rotate     !== 0) transforms.push({ rotate: `${props.rotate}deg` });
+    if (props.scale      !== undefined && props.scale      !== 1) transforms.push({ scale: props.scale });
+    if (props.translateX !== undefined && props.translateX !== 0) transforms.push({ translateX: props.translateX });
+    if (props.translateY !== undefined && props.translateY !== 0) transforms.push({ translateY: props.translateY });
+    return transforms.length ? { transform: transforms } : {};
+}
+
+function resolvePositionRN(props: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    if (props.position) out.position = props.position;
+    if (props.position === 'absolute') {
+        if (props.top    !== undefined) out.top    = props.top;
+        if (props.right  !== undefined) out.right  = props.right;
+        if (props.bottom !== undefined) out.bottom = props.bottom;
+        if (props.left   !== undefined) out.left   = props.left;
+    }
+    if (props.zIndex !== undefined) out.zIndex = props.zIndex;
+    return out;
+}
+
+function resolveAccessibilityProps(props: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    if (props.accessible      !== undefined) out.accessible          = props.accessible;
+    if (props.accessibilityLabel)            out.accessibilityLabel  = props.accessibilityLabel;
+    if (props.accessibilityRole)             out.accessibilityRole   = props.accessibilityRole;
+    if (props.testID)                        out.testID              = props.testID;
+    return out;
+}
+
+// ─── Full frame-style builder ─────────────────────────────────────────────────
+
+function buildFrameStyle(
+    props: Record<string, unknown>,
+    parentDirection: 'vertical' | 'horizontal',
+): Record<string, unknown> {
+    const style: Record<string, unknown> = {};
+    const frameType = (props.type as string | undefined) ?? 'stack';
+
+    if (frameType === 'grid') {
+        if (props.align) style.alignItems = ALIGN_MAP[props.align as string] ?? props.align;
+    } else {
+        style.flexDirection = props.direction === 'horizontal' ? 'row' : 'column';
+        if (props.align)      style.alignItems     = ALIGN_MAP[props.align as string]       ?? props.align;
+        if (props.distribute) style.justifyContent = DISTRIBUTE_MAP[props.distribute as string] ?? props.distribute;
+        if (props.gap !== undefined && props.gap !== 0) style.gap = props.gap;
+        if (props.wrap === 'yes') style.flexWrap = 'wrap';
+    }
+
+    resolveSizeModeRN(props.width  as SizeModeValue | undefined, 'width',  style, parentDirection);
+    resolveSizeModeRN(props.height as SizeModeValue | undefined, 'height', style, parentDirection);
+    if (props.minWidth   !== undefined) style.minWidth   = props.minWidth;
+    if (props.maxWidth   !== undefined) style.maxWidth   = props.maxWidth;
+    if (props.minHeight  !== undefined) style.minHeight  = props.minHeight;
+    if (props.maxHeight  !== undefined) style.maxHeight  = props.maxHeight;
+    if (props.aspectRatio !== undefined) style.aspectRatio = props.aspectRatio;
+
+    Object.assign(style, resolvePaddingRN(props.padding as SpacingValue | undefined));
+
+    if (props.fill && props.fill !== 'transparent') style.backgroundColor = props.fill;
+    Object.assign(style, resolveRadiusRN(props.radius as RadiusValue | undefined));
+    Object.assign(style, resolveBorderRN(props.border as BorderValue | undefined));
+    Object.assign(style, resolveShadowRN(props.shadow as ShadowValue | undefined));
+    if (props.opacity  !== undefined) style.opacity  = (props.opacity as number) / 100;
+    if (props.overflow === true)      style.overflow = 'hidden';
+
+    Object.assign(style, resolvePositionRN(props));
+    Object.assign(style, resolveTransformRN(props as Parameters<typeof resolveTransformRN>[0]));
+
+    return style;
+}
+
+function splitFrameStyle(style: Record<string, unknown>): {
+    outer: Record<string, unknown>;
+    inner: Record<string, unknown>;
+} {
+    const OUTER_KEYS = new Set([
+        'flex', 'alignSelf', 'width', 'height',
+        'minWidth', 'maxWidth', 'minHeight', 'maxHeight', 'aspectRatio',
+        'position', 'top', 'right', 'bottom', 'left', 'zIndex',
+        'transform',
+    ]);
+    const outer: Record<string, unknown> = {};
+    const inner: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(style)) {
+        if (OUTER_KEYS.has(k)) outer[k] = v;
+        else                   inner[k] = v;
+    }
+    return { outer, inner };
+}
+
+function splitScrollStyle(style: Record<string, unknown>): {
+    containerStyle: Record<string, unknown>;
+    contentStyle:   Record<string, unknown>;
+} {
+    const CONTENT_KEYS = new Set([
+        'flexDirection', 'justifyContent', 'alignItems', 'flexWrap', 'gap',
+        'padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft',
+        'paddingVertical', 'paddingHorizontal',
+    ]);
+    const containerStyle: Record<string, unknown> = {};
+    const contentStyle:   Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(style)) {
+        if (CONTENT_KEYS.has(k)) contentStyle[k]   = v;
+        else                     containerStyle[k] = v;
+    }
+    return { containerStyle, contentStyle };
+}
+
+// ─── Safe area helper ─────────────────────────────────────────────────────────
+
+function safeAreaEdges(safeArea: SafeAreaValue | undefined): string[] {
+    if (!safeArea) return [];
+    return (Object.entries(safeArea) as [string, boolean][])
+        .filter(([, v]) => v === true)
+        .map(([edge]) => edge);
+}
+
+// ─── Custom component definition ──────────────────────────────────────────────
+
+export interface CustomComponentDef {
+    rootNodeId: string;
+    nodes: CraftSchema;
+}
+
+export type CustomComponentsMap = Record<string, CustomComponentDef>;
+
+// ─── Node transformers ────────────────────────────────────────────────────────
+
+function transformScreen(
+    id: string,
+    raw: Record<string, unknown>,
+    children: SDUINode[],
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const edges      = safeAreaEdges(props.safeArea as SafeAreaValue | undefined);
+    const hasSafeArea = edges.length > 0;
+    const vis = props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {};
+
+    const style: Record<string, unknown> = { flex: 1 };
+    if (props.backgroundColor) style.backgroundColor = props.backgroundColor;
+
+    let content: SDUINode[];
+    if (props.scrollable) {
+        const paddingStyle = resolvePaddingRN(props.padding as SpacingValue | undefined);
+        const scrollNode: SDUINode = {
+            id: `${id}__scroll`,
+            type: 'scrollview',
+            props: {
+                style: { flex: 1 },
+                ...(Object.keys(paddingStyle).length ? { contentContainerStyle: paddingStyle } : {}),
+                showsVerticalScrollIndicator:   false,
+                showsHorizontalScrollIndicator: false,
+            },
+            children,
+        };
+        content = [scrollNode];
+    } else {
+        Object.assign(style, resolvePaddingRN(props.padding as SpacingValue | undefined));
+        content = children;
+    }
+
+    const statusBar = props.statusBarStyle && props.statusBarStyle !== 'dark'
+        ? { statusBarStyle: props.statusBarStyle }
+        : {};
+
+    const node: SDUINode = {
+        id,
+        type: hasSafeArea ? 'safeareaview' : 'view',
+        props: {
+            style,
+            ...(hasSafeArea ? { edges } : {}),
+            ...statusBar,
+            ...vis,
+        },
+        children: content,
+    };
+
+    if (condition !== undefined) node.if = condition;
+    if (actions)                 node.actions = actions;
+    return node;
+}
+
+function transformFrame(
+    id: string,
+    raw: Record<string, unknown>,
+    children: SDUINode[],
+    parentDirection: 'vertical' | 'horizontal',
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const p = stripBridgeKeys(raw);
+
+    const isGrid       = ((p.type as string | undefined) ?? 'stack') === 'grid';
+    const isScrollable = p.scrollable === true;
+    const isPressable  = p.pressable  === true;
+    const direction: 'vertical' | 'horizontal' = p.direction === 'horizontal' ? 'horizontal' : 'vertical';
+    const edges        = safeAreaEdges(p.safeArea as SafeAreaValue | undefined);
+    const hasSafeArea  = edges.length > 0;
+    const access       = resolveAccessibilityProps(p);
+    const vis          = p.visible !== undefined && p.visible !== true ? { visible: p.visible } : {};
+
+    const fullStyle                                      = buildFrameStyle(p, parentDirection);
+    const { outer: sizingStyle, inner: appearanceStyle } = splitFrameStyle(fullStyle);
+    const { containerStyle: scrollOuter, contentStyle: scrollContent } = splitScrollStyle(fullStyle);
+
+    function finalize(node: SDUINode): SDUINode {
+        if (condition !== undefined) node.if = condition;
+        if (actions && node.type === 'pressable') node.actions = actions;
+        else if (actions && !isPressable)          node.actions = actions;
+        return node;
+    }
+
+    // ── Grid ──────────────────────────────────────────────────────────────────
+    if (isGrid) {
+        const gridStyle: Record<string, unknown> = { ...fullStyle, flexDirection: 'row', flexWrap: 'wrap' };
+        delete gridStyle.gap;
+        if (p.columnGap !== undefined) gridStyle.columnGap = p.columnGap;
+        if (p.rowGap    !== undefined) gridStyle.rowGap    = p.rowGap;
+
+        const gridView: SDUINode = {
+            id: hasSafeArea || isPressable ? `${id}__grid` : id,
+            type: 'view',
+            props: {
+                ...(Object.keys(gridStyle).length ? { style: gridStyle } : {}),
+                numColumns: (p.columns as number | undefined) ?? 2,
+                ...access,
+                ...(hasSafeArea || isPressable ? {} : vis),
+            },
+            children,
+        };
+
+        if (!hasSafeArea && !isPressable) return finalize(gridView);
+
+        let inner: SDUINode = gridView;
+
+        if (hasSafeArea) {
+            inner = {
+                id: isPressable ? `${id}__sav` : id,
+                type: 'safeareaview',
+                props: { edges, ...(isPressable ? {} : vis) },
+                children: [gridView],
+            };
+        }
+
+        if (!isPressable) return finalize(inner);
+
+        return finalize({
+            id,
+            type: 'pressable',
+            props: {
+                ...(Object.keys(sizingStyle).length ? { style: sizingStyle } : {}),
+                ...(actions ? { actions } : {}),
+                ...vis,
+            },
+            children: [inner],
+        });
+    }
+
+    // ── Scrollable ────────────────────────────────────────────────────────────
+    if (isScrollable) {
+        const scrollNode: SDUINode = {
+            id: hasSafeArea || isPressable ? `${id}__scroll` : id,
+            type: 'scrollview',
+            props: {
+                ...(Object.keys(scrollOuter).length ? { style: scrollOuter } : {}),
+                ...(Object.keys(scrollContent).length ? { contentContainerStyle: scrollContent } : {}),
+                horizontal: direction === 'horizontal',
+                showsHorizontalScrollIndicator: p.showScrollIndicator === true,
+                showsVerticalScrollIndicator:   p.showScrollIndicator === true,
+                ...access,
+                ...(hasSafeArea || isPressable ? {} : vis),
+            },
+            children,
+        };
+
+        if (!hasSafeArea && !isPressable) return finalize(scrollNode);
+
+        let inner: SDUINode = scrollNode;
+
+        if (hasSafeArea) {
+            inner = {
+                id: isPressable ? `${id}__sav` : id,
+                type: 'safeareaview',
+                props: {
+                    edges,
+                    ...(Object.keys(sizingStyle).length ? { style: sizingStyle } : {}),
+                    ...(isPressable ? {} : vis),
+                },
+                children: [scrollNode],
+            };
+        }
+
+        if (!isPressable) return finalize(inner);
+
+        return finalize({
+            id,
+            type: 'pressable',
+            props: {
+                ...(Object.keys(sizingStyle).length ? { style: sizingStyle } : {}),
+                ...(actions ? { actions } : {}),
+                ...vis,
+            },
+            children: [inner],
+        });
+    }
+
+    // ── Plain view / safeareaview ─────────────────────────────────────────────
+
+    if (!isPressable && !hasSafeArea) {
+        return finalize({
+            id,
+            type: 'view',
+            props: {
+                ...(Object.keys(fullStyle).length ? { style: fullStyle } : {}),
+                ...access,
+                ...vis,
+            },
+            children,
+        });
+    }
+
+    if (!isPressable && hasSafeArea) {
+        return finalize({
+            id,
+            type: 'safeareaview',
+            props: {
+                edges,
+                ...(Object.keys(fullStyle).length ? { style: fullStyle } : {}),
+                ...access,
+                ...vis,
+            },
+            children,
+        });
+    }
+
+    // isPressable === true
+    const innerNode: SDUINode = hasSafeArea
+        ? {
+            id: `${id}__sav`,
+            type: 'safeareaview',
+            props: {
+                edges,
+                ...(Object.keys(appearanceStyle).length ? { style: appearanceStyle } : {}),
+                ...access,
+            },
+            children,
+          }
+        : {
+            id: `${id}__content`,
+            type: 'view',
+            props: {
+                ...(Object.keys(appearanceStyle).length ? { style: appearanceStyle } : {}),
+                ...access,
+            },
+            children,
+          };
+
+    return finalize({
+        id,
+        type: 'pressable',
+        props: {
+            ...(Object.keys(sizingStyle).length ? { style: sizingStyle } : {}),
+            ...(actions ? { actions } : {}),
+            ...vis,
+        },
+        children: [innerNode],
+    });
+}
+
+function transformText(
+    id: string,
+    raw: Record<string, unknown>,
+    parentDirection: 'vertical' | 'horizontal',
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const style: Record<string, unknown> = {};
+
+    if (props.textStyle) {
+        const preset = TEXT_STYLE_PRESETS[props.textStyle as string];
+        if (preset) {
+            style.fontSize   = preset.fontSize;
+            style.fontWeight = preset.fontWeight;
+            if (preset.lineHeight    !== undefined) style.lineHeight    = preset.lineHeight;
+            if (preset.textTransform)               style.textTransform = preset.textTransform;
+            if (preset.letterSpacing !== undefined) style.letterSpacing = preset.letterSpacing;
+        }
+    }
+
+    if (props.color)                                          style.color              = props.color;
+    if (props.fontSize       !== undefined)                   style.fontSize           = props.fontSize;
+    if (props.fontWeight)                                     style.fontWeight         = FONT_WEIGHT_MAP[props.fontWeight as string] ?? props.fontWeight;
+    if (props.fontFamily)                                     style.fontFamily         = props.fontFamily;
+    if (props.fontStyle)                                      style.fontStyle          = props.fontStyle;
+    if (props.lineHeight     !== undefined)                   style.lineHeight         = props.lineHeight;
+    if (props.letterSpacing  !== undefined)                   style.letterSpacing      = props.letterSpacing;
+    if (props.align)                                          style.textAlign          = props.align;
+    if (props.transform && props.transform !== 'none')        style.textTransform      = props.transform;
+    if (props.decoration && props.decoration !== 'none')      style.textDecorationLine = props.decoration;
+    if (props.opacity !== undefined)                          style.opacity            = (props.opacity as number) / 100;
+    Object.assign(style, resolvePositionRN(props));
+    resolveSizeModeRN(props.width as SizeModeValue | undefined, 'width', style, parentDirection);
+
+    const textProps: Record<string, unknown> = {};
+    if (typeof props.truncate === 'number' && props.truncate > 0) {
+        textProps.numberOfLines = props.truncate;
+        textProps.ellipsizeMode = 'tail';
+    }
+    if (props.adjustFontSize === true) {
+        textProps.adjustsFontSizeToFit = true;
+        if (props.minFontSize !== undefined) textProps.minimumFontScale = props.minFontSize;
+    }
+    if (props.selectable !== undefined) textProps.selectable = props.selectable;
+
+    const node: SDUINode = {
+        id,
+        type: 'text',
+        props: {
+            // SDK contract: text content lives in the `value` prop.
+            // The Craft editor stores text in `content`; map it to `value` here.
+            value: (props.content as string | undefined) ?? '',
+            ...(Object.keys(style).length ? { style } : {}),
+            ...textProps,
+            ...resolveAccessibilityProps(props),
+            ...(props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {}),
+        },
+    };
+    if (condition !== undefined) node.if = condition;
+    if (actions)                 node.actions = actions;
+    return node;
+}
+
+function transformImage(
+    id: string,
+    raw: Record<string, unknown>,
+    children: SDUINode[],
+    parentDirection: 'vertical' | 'horizontal',
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const style: Record<string, unknown> = {};
+    resolveSizeModeRN(props.width  as SizeModeValue | undefined, 'width',  style, parentDirection);
+    resolveSizeModeRN(props.height as SizeModeValue | undefined, 'height', style, parentDirection);
+    if (props.aspectRatio !== undefined) style.aspectRatio = props.aspectRatio;
+    Object.assign(style, resolveRadiusRN(props.radius as RadiusValue | undefined));
+    if (props.opacity !== undefined) style.opacity = (props.opacity as number) / 100;
+    Object.assign(style, resolvePositionRN(props));
+
+    const imageProps: Record<string, unknown> = {};
+    if (props.src)         imageProps.source        = { uri: props.src };
+    if (props.placeholder) imageProps.defaultSource = { uri: props.placeholder };
+    if (props.fallback)    imageProps.fallback       = { uri: props.fallback };
+    imageProps.resizeMode = FIT_TO_RESIZE_MODE[(props.fit as string | undefined) ?? 'cover'] ?? 'cover';
+
+    if (props.background === true) imageProps.background = true;
+
+    if (props.decorative) {
+        imageProps.accessible                  = false;
+        imageProps.accessibilityElementsHidden = true;
+    } else if (props.alt) {
+        imageProps.accessible         = true;
+        imageProps.accessibilityLabel = props.alt;
+    }
+    if (props.testID) imageProps.testID = props.testID;
+
+    const node: SDUINode = {
+        id,
+        type: 'image',
+        props: {
+            ...(Object.keys(style).length ? { style } : {}),
+            ...imageProps,
+            ...(props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {}),
+        },
+        ...(props.background === true && children.length ? { children } : {}),
+    };
+    if (condition !== undefined) node.if = condition;
+    if (actions)                 node.actions = actions;
+    return node;
+}
+
+function transformInput(
+    id: string,
+    raw: Record<string, unknown>,
+    parentDirection: 'vertical' | 'horizontal',
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const style: Record<string, unknown> = {};
+    resolveSizeModeRN((props.width as SizeModeValue | undefined) ?? 'fill', 'width', style, parentDirection);
+    Object.assign(style, resolvePaddingRN(props.padding as SpacingValue | undefined));
+    if (props.opacity !== undefined) style.opacity = (props.opacity as number) / 100;
+    Object.assign(style, resolvePositionRN(props));
+
+    const inputTypeDefaults = INPUT_TYPE_MAP[(props.inputType as string | undefined) ?? 'text'] ?? INPUT_TYPE_MAP.text;
+
+    const node: SDUINode = {
+        id,
+        type: 'textinput',
+        props: {
+            ...(Object.keys(style).length ? { style } : {}),
+            ...(props.label       !== undefined ? { label:       props.label       } : {}),
+            ...(props.placeholder !== undefined ? { placeholder: props.placeholder } : {}),
+            ...(props.value       !== undefined ? { value:       props.value       } : {}),
+            ...(props.helperText  !== undefined ? { helperText:  props.helperText  } : {}),
+            ...(props.errorText   !== undefined ? { errorText:   props.errorText   } : {}),
+            ...inputTypeDefaults,
+            ...(props.autoCapitalize ? { autoCapitalize: props.autoCapitalize } : {}),
+            returnKeyType: (props.returnKey as string | undefined) ?? 'done',
+            multiline: (props.multiline as boolean | undefined) ?? false,
+            ...(props.multiline && props.minLines ? { numberOfLines:    props.minLines } : {}),
+            ...(props.multiline && props.maxLines ? { maxNumberOfLines: props.maxLines } : {}),
+            variant: (props.variant as string | undefined) ?? 'outline',
+            size:    (props.size    as string | undefined) ?? 'md',
+            ...(props.leadingIcon  ? { leadingIcon:  props.leadingIcon  } : {}),
+            ...(props.trailingIcon ? { trailingIcon: props.trailingIcon } : {}),
+            ...resolveAccessibilityProps(props),
+            ...(props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {}),
+        },
+    };
+    if (condition !== undefined) node.if = condition;
+    if (actions)                 node.actions = actions;
+    return node;
+}
+
+function transformList(
+    id: string,
+    raw: Record<string, unknown>,
+    children: SDUINode[],
+    parentDirection: 'vertical' | 'horizontal',
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const listType = (props.type as string | undefined) ?? 'stack';
+    const direction: 'vertical' | 'horizontal' = props.direction === 'horizontal' ? 'horizontal' : 'vertical';
+    const edges       = safeAreaEdges(props.safeArea as SafeAreaValue | undefined);
+    const hasSafeArea = edges.length > 0;
+    const vis         = props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {};
+
+    const fullStyle = buildFrameStyle(props, parentDirection);
+    const { containerStyle, contentStyle } = splitScrollStyle(fullStyle);
+
+    // Children of PF.List are the per-item template.
+    let itemTemplate: SDUINode | undefined;
+    if (children.length === 1) {
+        itemTemplate = children[0];
+    } else if (children.length > 1) {
+        itemTemplate = { id: `${id}__template`, type: 'view', props: {}, children };
+    }
+
+    const flatlistNode: SDUINode = {
+        id: hasSafeArea ? `${id}__list` : id,
+        type: 'flatlist',
+        props: {
+            ...(Object.keys(containerStyle).length ? { style: containerStyle } : {}),
+            ...(Object.keys(contentStyle).length   ? { contentContainerStyle: contentStyle } : {}),
+            // `data` holds the binding expression for the list items array.
+            // RecursiveRenderer resolves it and passes items to the FlatList primitive.
+            data:         props.data,
+            keyExtractor: (props.keyExtractor as string | undefined) ?? 'id',
+            ...(listType === 'grid' ? { numColumns: (props.columns as number | undefined) ?? 2 } : {}),
+            ...(listType === 'grid' && props.columnGap ? { columnGap: props.columnGap } : {}),
+            ...(listType === 'grid' && props.rowGap    ? { rowGap:    props.rowGap    } : {}),
+            horizontal:                     direction === 'horizontal',
+            showsHorizontalScrollIndicator: props.showScrollIndicator === true,
+            showsVerticalScrollIndicator:   props.showScrollIndicator === true,
+            ...resolveAccessibilityProps(props),
+            ...(hasSafeArea ? {} : vis),
+        },
+        ...(itemTemplate ? { itemTemplate } : {}),
+    };
+
+    if (!hasSafeArea) {
+        if (condition !== undefined) flatlistNode.if = condition;
+        if (actions)                 flatlistNode.actions = actions;
+        return flatlistNode;
+    }
+
+    const { outer: sizingStyle } = splitFrameStyle(fullStyle);
+    const savNode: SDUINode = {
+        id,
+        type: 'safeareaview',
+        props: {
+            edges,
+            ...(Object.keys(sizingStyle).length ? { style: sizingStyle } : {}),
+            ...vis,
+        },
+        children: [flatlistNode],
+    };
+    if (condition !== undefined) savNode.if = condition;
+    if (actions)                 savNode.actions = actions;
+    return savNode;
+}
+
+function transformIcon(
+    id: string,
+    raw: Record<string, unknown>,
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const style: Record<string, unknown> = {};
+    if (props.opacity !== undefined) style.opacity = (props.opacity as number) / 100;
+    Object.assign(style, resolvePositionRN(props));
+
+    const node: SDUINode = {
+        id,
+        type: 'icon',
+        props: {
+            name: props.name,
+            set:  (props.set as string | undefined) ?? 'default',
+            size: (props.size as number | undefined) ?? 24,
+            ...(props.color ? { color: props.color } : {}),
+            ...(Object.keys(style).length ? { style } : {}),
+            ...resolveAccessibilityProps(props),
+            ...(props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {}),
+        },
+    };
+    if (condition !== undefined) node.if = condition;
+    if (actions)                 node.actions = actions;
+    return node;
+}
+
+// ─── Core recursive builder ───────────────────────────────────────────────────
+
+function buildNodeFromSchema(
+    nodeId: string,
+    schema: CraftSchema,
+    customComponents: CustomComponentsMap,
+    visited: Set<string>,
+    parentId?: string,
+): SDUINode {
+    if (visited.has(nodeId)) {
+        throw new Error(`Circular reference detected at node ${nodeId}`);
+    }
+    visited.add(nodeId);
+
+    const node = schema[nodeId];
+    if (!node) throw new Error(`Node not found: ${nodeId}`);
+
+    const resolvedName = node.type?.resolvedName;
+    if (!resolvedName) throw new Error(`Invalid node type at ${nodeId}`);
+
+    const raw = (node.props ?? {}) as Record<string, unknown>;
+    const parentDirection: 'vertical' | 'horizontal' = parentId
+        ? (schema[parentId]?.props?.['direction'] === 'horizontal' ? 'horizontal' : 'vertical')
+        : 'vertical';
+    const outputId = nodeId === 'ROOT' ? 'root' : nodeId;
+
+    const childNodes = (node.nodes ?? []).map(childId =>
+        buildNodeFromSchema(childId, schema, customComponents, visited, nodeId),
+    );
+
+    switch (resolvedName) {
+        case 'PF.Screen':
+            return transformScreen(outputId, raw, childNodes);
+
+        case 'PF.Frame':
+            return transformFrame(outputId, raw, childNodes, parentDirection);
+
+        case 'PF.Text':
+            return transformText(outputId, raw, parentDirection);
+
+        case 'PF.Image':
+            return transformImage(outputId, raw, childNodes, parentDirection);
+
+        case 'PF.Input':
+            return transformInput(outputId, raw, parentDirection);
+
+        case 'PF.List':
+            return transformList(outputId, raw, childNodes, parentDirection);
+
+        case 'PF.Icon':
+            return transformIcon(outputId, raw);
+
+        case 'Component':
+            return resolveCustomComponent(outputId, raw, parentDirection, customComponents);
+
+        default:
+            return { id: outputId, type: 'view', props: {}, children: childNodes };
+    }
+}
+
+// ─── Custom component inliner ─────────────────────────────────────────────────
+
+function resolveCustomComponent(
+    id: string,
+    raw: Record<string, unknown>,
+    parentDirection: 'vertical' | 'horizontal',
+    customComponents: CustomComponentsMap,
+): SDUINode {
+    const { actions, condition } = extractMeta(raw);
+    const props = stripBridgeKeys(raw);
+
+    const { componentId, componentKey, propValues, ...frameProps } = props as {
+        componentId?: string;
+        componentKey?: string;
+        propValues?: Record<string, unknown>;
+        [k: string]: unknown;
+    };
+    const key = componentKey ?? componentId;
+    const def = key ? customComponents[key] : undefined;
+
+    const wrapperStyle = buildFrameStyle(frameProps, parentDirection);
+    const vis = props.visible !== undefined && props.visible !== true ? { visible: props.visible } : {};
+
+    if (!def) {
+        return {
+            id,
+            type: 'view',
+            props: { ...(Object.keys(wrapperStyle).length ? { style: wrapperStyle } : {}), ...vis },
+            children: [],
+        };
+    }
+
+    const componentVisited = new Set<string>();
+    const componentRoot = buildNodeFromSchema(
+        def.rootNodeId,
+        def.nodes,
+        customComponents,
+        componentVisited,
+    );
+
+    if (propValues && Object.keys(propValues).length) {
+        componentRoot.props = { ...componentRoot.props, _propValues: propValues };
+    }
+
+    if (Object.keys(wrapperStyle).length > 0) {
+        const wrapper: SDUINode = {
+            id,
+            type: 'view',
+            props: { style: wrapperStyle, ...vis },
+            children: [componentRoot],
+        };
+        if (condition !== undefined) wrapper.if = condition;
+        if (actions)                 wrapper.actions = actions;
+        return wrapper;
+    }
+
+    componentRoot.id    = id;
+    componentRoot.props = { ...componentRoot.props, ...vis };
+    if (condition !== undefined) componentRoot.if = condition;
+    if (actions)                 componentRoot.actions = actions;
+    return componentRoot;
+}
+
+// ─── Main entry ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert a Craft.js editor schema into an SDUINode tree ready for the SDK's
+ * RecursiveRenderer.
+ *
+ * @param craftJson   - The full Craft.js node map (keyed by node ID, must include "ROOT").
+ * @param customComponents - Optional map of reusable component definitions.
+ * @returns The root SDUINode.
+ */
+export function transformCraftToSDUI(
+    craftJson: CraftSchema,
+    customComponents: CustomComponentsMap = {},
+): SDUINode {
+    if (!craftJson || typeof craftJson !== 'object') {
+        throw new Error('Invalid craft schema');
+    }
+
+    const visited = new Set<string>();
+    return buildNodeFromSchema('ROOT', craftJson, customComponents, visited);
+}