@efectoapp/mcp-server 0.1.18 → 0.1.21

package/dist/tools/state.js

@@ -85,7 +85,7 @@ function getDefaultAnimationParams(type) {
     const base = {
         type,
         enabled: true,
-        speed: 1.0,
+        speed: 0.2,
         amplitude: 50,
         staggerDelay: 150,
         staggerMode: 'sequential',
@@ -289,8 +289,118 @@ function createDefaultBackgroundLayer(backgroundColor) {
         },
         contentType: 'solid',
         solidColor: backgroundColor,
+        fill: {
+            type: 'solid',
+            color: backgroundColor,
+            opacity: 1,
+        },
+    };
+}
+const DEFAULT_LINEAR_GRADIENT_FILL = {
+    type: 'linear',
+    angle: 135,
+    stops: [
+        { color: '#7c3aed', opacity: 1, position: 0 },
+        { color: '#22d3ee', opacity: 1, position: 1 },
+    ],
+};
+const DEFAULT_RADIAL_GRADIENT_FILL = {
+    type: 'radial',
+    center: { x: 0.5, y: 0.5 },
+    radius: 0.8,
+    stops: [
+        { color: '#a78bfa', opacity: 1, position: 0 },
+        { color: '#0f172a', opacity: 1, position: 1 },
+    ],
+};
+const MIN_GRADIENT_STOPS = 2;
+const MAX_GRADIENT_STOPS = 8;
+function clamp01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function normalizeAngle(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    const normalized = value % 360;
+    return normalized < 0 ? normalized + 360 : normalized;
+}
+function clampRadius(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_RADIAL_GRADIENT_FILL.radius;
+    return Math.min(2, Math.max(0.05, value));
+}
+function isHexColor(value) {
+    return /^#[0-9a-fA-F]{3}$/.test(value) || /^#[0-9a-fA-F]{6}$/.test(value);
+}
+function normalizeGradientStop(stop, fallback) {
+    return {
+        color: isHexColor(stop.color) ? stop.color : fallback.color,
+        opacity: clamp01(stop.opacity),
+        position: clamp01(stop.position),
+    };
+}
+function normalizeGradientStops(stops, fallbackStops) {
+    const fallbackStart = fallbackStops[0];
+    const fallbackEnd = fallbackStops[fallbackStops.length - 1] ?? fallbackStart;
+    const input = Array.isArray(stops) ? stops : [];
+    const normalized = input
+        .map((stop, index) => normalizeGradientStop(stop, fallbackStops[Math.min(index, fallbackStops.length - 1)] ?? fallbackEnd))
+        .slice(0, MAX_GRADIENT_STOPS);
+    if (normalized.length < MIN_GRADIENT_STOPS) {
+        if (normalized.length === 0) {
+            normalized.push(normalizeGradientStop(fallbackStart, fallbackStart), normalizeGradientStop(fallbackEnd, fallbackEnd));
+        }
+        else if (normalized.length === 1) {
+            normalized.push(normalizeGradientStop(fallbackEnd, fallbackEnd));
+        }
+    }
+    return normalized
+        .map((stop, index) => ({ stop, index }))
+        .sort((a, b) => a.stop.position - b.stop.position || a.index - b.index)
+        .map(({ stop }) => stop);
+}
+function normalizeLinearGradientFill(fill) {
+    const fallback = DEFAULT_LINEAR_GRADIENT_FILL;
+    return {
+        type: 'linear',
+        angle: normalizeAngle(fill.angle),
+        stops: normalizeGradientStops(fill.stops, fallback.stops),
     };
 }
+function normalizeRadialGradientFill(fill) {
+    const fallback = DEFAULT_RADIAL_GRADIENT_FILL;
+    return {
+        type: 'radial',
+        center: {
+            x: clamp01(fill.center?.x ?? fallback.center.x),
+            y: clamp01(fill.center?.y ?? fallback.center.y),
+        },
+        radius: clampRadius(fill.radius),
+        stops: normalizeGradientStops(fill.stops, fallback.stops),
+    };
+}
+function parseGradientStopsInput(input, fallbackStops) {
+    if (!Array.isArray(input))
+        return null;
+    const parsed = input
+        .map((item, index) => {
+        if (!item || typeof item !== 'object')
+            return null;
+        const candidate = item;
+        const fallback = fallbackStops[Math.min(index, fallbackStops.length - 1)] ?? fallbackStops[0];
+        const opacityRaw = typeof candidate.opacity === 'number' ? candidate.opacity : Number.parseFloat(String(candidate.opacity ?? ''));
+        const positionRaw = typeof candidate.position === 'number' ? candidate.position : Number.parseFloat(String(candidate.position ?? ''));
+        return {
+            color: typeof candidate.color === 'string' && isHexColor(candidate.color) ? candidate.color : fallback.color,
+            opacity: clamp01(Number.isFinite(opacityRaw) ? opacityRaw : fallback.opacity),
+            position: clamp01(Number.isFinite(positionRaw) ? positionRaw : fallback.position),
+        };
+    })
+        .filter((stop) => stop !== null);
+    return parsed.length >= MIN_GRADIENT_STOPS ? parsed : null;
+}
 // Tool definitions
 exports.stateTools = [
     {
@@ -301,7 +411,7 @@ exports.stateTools = [
             properties: {
                 aspectRatio: {
                     type: 'string',
-                    enum: ['16:9', '9:16', '1:1', '4:3', 'full'],
+                    enum: ['16:9', '9:16', '1:1', '4:3', '3:4', 'full'],
                     description: 'Canvas aspect ratio (default: 9:16 for portrait poster)',
                     default: '9:16',
                 },
@@ -316,13 +426,13 @@ exports.stateTools = [
     },
     {
         name: 'set_background',
-        description: 'Configure the background layer (always at index 0). Can be solid color, image, or video.',
+        description: 'Configure the background layer (always at index 0). Can be solid fill, linear/radial gradient fill, image, or video.',
         inputSchema: {
             type: 'object',
             properties: {
                 type: {
                     type: 'string',
-                    enum: ['solid', 'image', 'video'],
+                    enum: ['solid', 'gradient', 'image', 'video'],
                     description: 'Background content type',
                     default: 'solid',
                 },
@@ -330,6 +440,50 @@ exports.stateTools = [
                     type: 'string',
                     description: 'Solid background color in hex (for type: solid)',
                 },
+                gradientStartColor: {
+                    type: 'string',
+                    description: 'Gradient start color in hex (for type: gradient)',
+                },
+                gradientEndColor: {
+                    type: 'string',
+                    description: 'Gradient end color in hex (for type: gradient)',
+                },
+                gradientStops: {
+                    type: 'array',
+                    description: 'Optional gradient stops array (2-8 items). If provided, overrides start/end colors.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            color: { type: 'string', description: 'Stop color in hex' },
+                            opacity: { type: 'number', description: 'Stop opacity (0-1)' },
+                            position: { type: 'number', description: 'Stop position (0-1)' },
+                        },
+                        required: ['color', 'position'],
+                    },
+                    minItems: 2,
+                    maxItems: 8,
+                },
+                gradientStyle: {
+                    type: 'string',
+                    enum: ['linear', 'radial'],
+                    description: 'Gradient style (for type: gradient)',
+                },
+                gradientAngle: {
+                    type: 'number',
+                    description: 'Linear gradient angle in degrees (for linear style)',
+                },
+                gradientCenterX: {
+                    type: 'number',
+                    description: 'Radial center X (0-1, for radial style)',
+                },
+                gradientCenterY: {
+                    type: 'number',
+                    description: 'Radial center Y (0-1, for radial style)',
+                },
+                gradientRadius: {
+                    type: 'number',
+                    description: 'Radial radius scale (for radial style)',
+                },
                 imageUrl: {
                     type: 'string',
                     description: 'Image URL (for type: image)',
@@ -369,13 +523,19 @@ exports.stateTools = [
                 opacity: { type: 'number', description: 'Opacity 0-1', default: 1 },
                 // Text layer properties
                 content: { type: 'string', description: 'Text content (required for text layers)' },
+                textType: { type: 'string', enum: ['point', 'frame'], description: 'Text authoring mode: "frame" for layout copy with wrapping (recommended), "point" for scalable text', default: 'frame' },
                 fontFamily: { type: 'string', description: 'Font family name', default: 'DM Sans' },
                 fontSize: { type: 'number', description: 'Font size in pixels', default: 72 },
                 fontWeight: { type: 'string', enum: ['normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900'], description: 'Font weight', default: 'bold' },
                 color: { type: 'string', description: 'Text color in hex', default: '#ffffff' },
                 textAlign: { type: 'string', enum: ['left', 'center', 'right'], description: 'Text alignment', default: 'center' },
-                letterSpacing: { type: 'number', description: 'Letter spacing in pixels', default: 0 },
-                lineHeight: { type: 'number', description: 'Line height multiplier', default: 1.2 },
+                letterSpacing: { type: 'number', description: 'Letter spacing in pixels (negative for tighter, e.g., -1 to -2 for headlines)', default: 0 },
+                lineHeight: { type: 'number', description: 'Line height multiplier (0.9-1.0 for tight headlines, 1.3-1.5 for body)', default: 1.2 },
+                textTransformMode: { type: 'string', enum: ['scale', 'box'], description: 'Text sizing mode: "box" for natural wrapping (recommended), "scale" to stretch to fit', default: 'box' },
+                textBoxWidth: { type: 'number', description: 'Width in pixels for text wrapping when using box mode (e.g., 300-600 for readable lines)' },
+                frameWidthPx: { type: 'number', description: 'Frame width in CSS pixels for frame text (resizing changes this, not fontSize)' },
+                frameHeightPx: { type: 'number', description: 'Frame height in CSS pixels for frame text' },
+                autoSize: { type: 'string', enum: ['none', 'height', 'widthAndHeight'], description: 'Auto-size mode for frame text' },
                 // Text animation properties (use list_text_animations to see all options)
                 animationType: {
                     type: 'string',
@@ -453,9 +613,72 @@ exports.stateTools = [
             required: ['type'],
         },
     },
+    {
+        name: 'add_group',
+        description: 'Add a flexbox container with child layers. Works like CSS flexbox: set direction (column/row), alignment, and gap. Children are positioned automatically by the layout engine — do NOT set child x/y. Use this for ALL text layout (heading + subheading, title + date, etc.).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Group name' },
+                layoutMode: { type: 'string', enum: ['row', 'column'], description: 'Flex direction: "column" stacks vertically (default, most common), "row" places side by side', default: 'column' },
+                widthMode: { type: 'string', enum: ['hug', 'fixed'], description: 'Horizontal sizing mode: hug contents or fixed width' },
+                heightMode: { type: 'string', enum: ['hug', 'fixed'], description: 'Vertical sizing mode: hug contents or fixed height' },
+                gap: { type: 'number', description: 'Space between children (like CSS gap). 0.02=small, 0.04=medium, 0.06=large', default: 0.02 },
+                justifyContent: { type: 'string', enum: ['start', 'center', 'end', 'space-between', 'space-around', 'space-evenly'], description: 'Main-axis alignment (like CSS justify-content)', default: 'start' },
+                alignItems: { type: 'string', enum: ['start', 'center', 'end'], description: 'Cross-axis alignment (like CSS align-items): "start"=left, "center"=centered, "end"=right', default: 'center' },
+                wrap: { type: 'boolean', description: 'Wrap children to next line on overflow (like CSS flex-wrap)', default: false },
+                padding: { type: 'number', description: 'Inner padding (like CSS padding)', default: 0 },
+                paddingTop: { type: 'number', description: 'Top padding override' },
+                paddingRight: { type: 'number', description: 'Right padding override' },
+                paddingBottom: { type: 'number', description: 'Bottom padding override' },
+                paddingLeft: { type: 'number', description: 'Left padding override' },
+                fillColor: { type: 'string', description: 'Group background color (hex)' },
+                fillOpacity: { type: 'number', description: 'Group background opacity (0-1)' },
+                cornerRadius: { type: 'number', description: 'Corner radius' },
+                x: { type: 'number', description: 'Group X position (-1 to 1, 0 is center)', default: 0 },
+                y: { type: 'number', description: 'Group Y position (-1 to 1, POSITIVE is UP/TOP). 0.15=upper, 0=center, -0.3=lower', default: 0 },
+                width: { type: 'number', description: 'Group width (0-1 relative to canvas)', default: 0.6 },
+                height: { type: 'number', description: 'Group height (0-1 relative to canvas)', default: 0.4 },
+                rotation: { type: 'number', description: 'Rotation in degrees', default: 0 },
+                opacity: { type: 'number', description: 'Opacity 0-1', default: 1 },
+                children: {
+                    type: 'array',
+                    description: 'Child layers to add inside the group',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: { type: 'string', enum: ['text', 'image', 'video'], description: 'Child layer type' },
+                            name: { type: 'string', description: 'Child layer name' },
+                            content: { type: 'string', description: 'Text content' },
+                            fontFamily: { type: 'string', description: 'Font family' },
+                            fontSize: { type: 'number', description: 'Font size in pixels' },
+                            fontWeight: { type: 'string', description: 'Font weight' },
+                            color: { type: 'string', description: 'Text color in hex' },
+                            textAlign: { type: 'string', enum: ['left', 'center', 'right'], description: 'Text alignment' },
+                            letterSpacing: { type: 'number', description: 'Letter spacing' },
+                            lineHeight: { type: 'number', description: 'Line height multiplier' },
+                            textType: { type: 'string', enum: ['point', 'frame'], description: 'Text authoring mode' },
+                            textTransformMode: { type: 'string', enum: ['scale', 'box'], description: 'Text sizing mode' },
+                            textBoxWidth: { type: 'number', description: 'Width for text wrapping' },
+                            frameWidthPx: { type: 'number', description: 'Frame width in CSS pixels' },
+                            frameHeightPx: { type: 'number', description: 'Frame height in CSS pixels' },
+                            autoSize: { type: 'string', enum: ['none', 'height', 'widthAndHeight'], description: 'Auto-size mode' },
+                            mediaUrl: { type: 'string', description: 'Media URL (for image/video)' },
+                            objectFit: { type: 'string', enum: ['cover', 'contain'], description: 'Object fit mode' },
+                            width: { type: 'number', description: 'Child width (0-1 relative to group)' },
+                            height: { type: 'number', description: 'Child height (0-1 relative to group)' },
+                            opacity: { type: 'number', description: 'Opacity 0-1' },
+                        },
+                        required: ['type'],
+                    },
+                },
+            },
+            required: ['children'],
+        },
+    },
     {
         name: 'modify_layer',
-        description: 'Modify an existing layer by ID',
+        description: 'Modify an existing layer by ID. Supports text, image, video, and group properties.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -472,6 +695,7 @@ exports.stateTools = [
                 name: { type: 'string', description: 'Layer name' },
                 // Text layer properties
                 content: { type: 'string' },
+                textType: { type: 'string', enum: ['point', 'frame'], description: 'Text authoring mode' },
                 fontFamily: { type: 'string' },
                 fontSize: { type: 'number' },
                 fontWeight: { type: 'string' },
@@ -479,6 +703,11 @@ exports.stateTools = [
                 textAlign: { type: 'string' },
                 letterSpacing: { type: 'number' },
                 lineHeight: { type: 'number' },
+                textTransformMode: { type: 'string', enum: ['scale', 'box'] },
+                textBoxWidth: { type: 'number' },
+                frameWidthPx: { type: 'number' },
+                frameHeightPx: { type: 'number' },
+                autoSize: { type: 'string', enum: ['none', 'height', 'widthAndHeight'] },
                 // Text animation properties (all type-specific params supported - see add_layer for descriptions)
                 animationType: {
                     type: 'string',
@@ -535,6 +764,22 @@ exports.stateTools = [
                 // Media properties
                 mediaUrl: { type: 'string' },
                 objectFit: { type: 'string' },
+                // Group layout properties
+                layoutMode: { type: 'string', enum: ['row', 'column'], description: 'Group layout direction' },
+                widthMode: { type: 'string', enum: ['hug', 'fixed'], description: 'Group horizontal sizing mode' },
+                heightMode: { type: 'string', enum: ['hug', 'fixed'], description: 'Group vertical sizing mode' },
+                gap: { type: 'number', description: 'Gap between children (normalized 0-1)' },
+                justifyContent: { type: 'string', enum: ['start', 'center', 'end', 'space-between', 'space-around', 'space-evenly'], description: 'Group main-axis alignment' },
+                alignItems: { type: 'string', enum: ['start', 'center', 'end'], description: 'Group cross-axis alignment' },
+                wrap: { type: 'boolean', description: 'Group wrap children' },
+                padding: { type: 'number', description: 'Group uniform padding' },
+                paddingTop: { type: 'number', description: 'Group top padding' },
+                paddingRight: { type: 'number', description: 'Group right padding' },
+                paddingBottom: { type: 'number', description: 'Group bottom padding' },
+                paddingLeft: { type: 'number', description: 'Group left padding' },
+                fillColor: { type: 'string', description: 'Group background color' },
+                fillOpacity: { type: 'number', description: 'Group background opacity' },
+                cornerRadius: { type: 'number', description: 'Group corner radius' },
             },
             required: ['layerId'],
         },
@@ -765,13 +1010,79 @@ async function handleStateTool(name, args) {
                     content: [{ type: 'text', text: 'Error: Background layer not found at index 0' }],
                 };
             }
-            const contentType = params.type || 'solid';
+            const requestedType = params.type || 'solid';
+            const contentType = requestedType === 'gradient' ? 'solid' : requestedType;
             bgLayer.contentType = contentType;
-            if (contentType === 'solid') {
-                if (params.color) {
-                    bgLayer.solidColor = params.color;
-                    currentPoster.canvas.backgroundColor = params.color;
-                }
+            if (requestedType === 'gradient') {
+                const gradientStyle = params.gradientStyle === 'radial' ? 'radial' : 'linear';
+                const explicitStops = parseGradientStopsInput(params.gradientStops, gradientStyle === 'radial' ? DEFAULT_RADIAL_GRADIENT_FILL.stops : DEFAULT_LINEAR_GRADIENT_FILL.stops);
+                const gradient = gradientStyle === 'radial'
+                    ? normalizeRadialGradientFill({
+                        type: 'radial',
+                        center: {
+                            x: Number.isFinite(params.gradientCenterX)
+                                ? params.gradientCenterX
+                                : DEFAULT_RADIAL_GRADIENT_FILL.center.x,
+                            y: Number.isFinite(params.gradientCenterY)
+                                ? params.gradientCenterY
+                                : DEFAULT_RADIAL_GRADIENT_FILL.center.y,
+                        },
+                        radius: Number.isFinite(params.gradientRadius)
+                            ? params.gradientRadius
+                            : DEFAULT_RADIAL_GRADIENT_FILL.radius,
+                        stops: explicitStops ?? [
+                            {
+                                color: params.gradientStartColor || DEFAULT_RADIAL_GRADIENT_FILL.stops[0].color,
+                                opacity: DEFAULT_RADIAL_GRADIENT_FILL.stops[0].opacity,
+                                position: DEFAULT_RADIAL_GRADIENT_FILL.stops[0].position,
+                            },
+                            {
+                                color: params.gradientEndColor || DEFAULT_RADIAL_GRADIENT_FILL.stops[1].color,
+                                opacity: DEFAULT_RADIAL_GRADIENT_FILL.stops[1].opacity,
+                                position: DEFAULT_RADIAL_GRADIENT_FILL.stops[1].position,
+                            },
+                        ],
+                    })
+                    : normalizeLinearGradientFill({
+                        type: 'linear',
+                        angle: Number.isFinite(params.gradientAngle)
+                            ? params.gradientAngle
+                            : DEFAULT_LINEAR_GRADIENT_FILL.angle,
+                        stops: explicitStops ?? [
+                            {
+                                color: params.gradientStartColor || DEFAULT_LINEAR_GRADIENT_FILL.stops[0].color,
+                                opacity: DEFAULT_LINEAR_GRADIENT_FILL.stops[0].opacity,
+                                position: DEFAULT_LINEAR_GRADIENT_FILL.stops[0].position,
+                            },
+                            {
+                                color: params.gradientEndColor || DEFAULT_LINEAR_GRADIENT_FILL.stops[1].color,
+                                opacity: DEFAULT_LINEAR_GRADIENT_FILL.stops[1].opacity,
+                                position: DEFAULT_LINEAR_GRADIENT_FILL.stops[1].position,
+                            },
+                        ],
+                    });
+                bgLayer.fill = gradient;
+                bgLayer.solidColor = gradient.stops[0].color;
+                currentPoster.canvas.backgroundColor = gradient.stops[0].color;
+                delete bgLayer.inputMedia;
+            }
+            else if (contentType === 'solid') {
+                const solidColor = params.color ||
+                    (bgLayer.fill?.type === 'solid'
+                        ? bgLayer.fill.color
+                        : bgLayer.fill
+                            ? bgLayer.fill.stops[0]?.color
+                            : undefined) ||
+                    bgLayer.solidColor ||
+                    currentPoster.canvas.backgroundColor ||
+                    '#5c5c5c';
+                bgLayer.solidColor = solidColor;
+                bgLayer.fill = {
+                    type: 'solid',
+                    color: solidColor,
+                    opacity: 1,
+                };
+                currentPoster.canvas.backgroundColor = solidColor;
                 delete bgLayer.inputMedia;
             }
             else if (contentType === 'image' && params.imageUrl) {
@@ -843,11 +1154,17 @@ async function handleStateTool(name, args) {
             let layer;
             if (layerType === 'text') {
                 const animation = buildAnimationSettings(params);
+                // textType is canonical, textTransformMode is legacy. textType wins if both provided.
+                const requestedTextType = params.textType;
+                const requestedTransformMode = params.textTransformMode;
+                const textType = requestedTextType ?? (requestedTransformMode === 'scale' ? 'point' : 'frame');
+                const textTransformMode = textType === 'point' ? 'scale' : 'box';
                 // Use same defaults as app's DEFAULT_TEXT_LAYER to avoid encoding unnecessary params in URLs
                 layer = {
                     ...baseLayer,
                     type: 'text',
                     content: params.content || 'Text',
+                    textType,
                     fontFamily: normalizeFontFamily(params.fontFamily),
                     fontSize: params.fontSize || 72,
                     fontWeight: normalizeFontWeight(params.fontWeight),
@@ -855,7 +1172,12 @@ async function handleStateTool(name, args) {
                     textAlign: params.textAlign || 'center',
                     letterSpacing: params.letterSpacing ?? 0,
                     lineHeight: params.lineHeight ?? 1.2,
-                    ...(animation && { animation }),
+                    textTransformMode,
+                    ...(params.textBoxWidth ? { textBoxWidth: params.textBoxWidth } : {}),
+                    ...(params.frameWidthPx ? { frameWidthPx: params.frameWidthPx } : {}),
+                    ...(params.frameHeightPx ? { frameHeightPx: params.frameHeightPx } : {}),
+                    ...(params.autoSize ? { autoSize: params.autoSize } : {}),
+                    ...(animation ? { animation } : {}),
                 };
             }
             else if (layerType === 'image') {
@@ -910,6 +1232,154 @@ async function handleStateTool(name, args) {
                 ],
             };
         }
+        case 'add_group': {
+            if (!currentPoster) {
+                return {
+                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
+                };
+            }
+            const children = params.children;
+            if (!children || !Array.isArray(children) || children.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: children array is required and must have at least 1 child' }],
+                };
+            }
+            const groupId = generateId();
+            const childLayers = [];
+            for (const childParams of children) {
+                const childType = childParams.type || 'text';
+                const childId = generateId();
+                const childBase = {
+                    id: childId,
+                    type: childType,
+                    name: childParams.name || `${childType.charAt(0).toUpperCase() + childType.slice(1)} Layer`,
+                    visible: true,
+                    locked: false,
+                    transform: {
+                        x: 0,
+                        y: 0,
+                        width: childParams.width ?? 1,
+                        height: childParams.height ?? 1,
+                        rotation: 0,
+                        opacity: childParams.opacity ?? 1,
+                    },
+                };
+                if (childType === 'text') {
+                    const requestedTextType = childParams.textType;
+                    const requestedTransformMode = childParams.textTransformMode;
+                    const textType = requestedTextType ?? (requestedTransformMode === 'scale' ? 'point' : 'frame');
+                    const textTransformMode = textType === 'point' ? 'scale' : 'box';
+                    childLayers.push({
+                        ...childBase,
+                        type: 'text',
+                        content: childParams.content || 'Text',
+                        textType,
+                        fontFamily: normalizeFontFamily(childParams.fontFamily),
+                        fontSize: childParams.fontSize || 72,
+                        fontWeight: normalizeFontWeight(childParams.fontWeight),
+                        color: childParams.color || '#ffffff',
+                        textAlign: childParams.textAlign || 'center',
+                        letterSpacing: childParams.letterSpacing ?? 0,
+                        lineHeight: childParams.lineHeight ?? 1.2,
+                        textTransformMode,
+                        ...(childParams.textBoxWidth ? { textBoxWidth: childParams.textBoxWidth } : {}),
+                        ...(childParams.frameWidthPx ? { frameWidthPx: childParams.frameWidthPx } : {}),
+                        ...(childParams.frameHeightPx ? { frameHeightPx: childParams.frameHeightPx } : {}),
+                        ...(childParams.autoSize ? { autoSize: childParams.autoSize } : {}),
+                    });
+                }
+                else if (childType === 'image') {
+                    if (!childParams.mediaUrl)
+                        continue;
+                    childLayers.push({
+                        ...childBase,
+                        type: 'image',
+                        mediaUrl: childParams.mediaUrl,
+                        objectFit: childParams.objectFit || 'cover',
+                        brightness: 1,
+                        contrast: 1,
+                        saturation: 1,
+                    });
+                }
+                else if (childType === 'video') {
+                    if (!childParams.mediaUrl)
+                        continue;
+                    childLayers.push({
+                        ...childBase,
+                        type: 'video',
+                        mediaUrl: childParams.mediaUrl,
+                        objectFit: childParams.objectFit || 'cover',
+                        brightness: 1,
+                        contrast: 1,
+                        saturation: 1,
+                        loop: true,
+                        playbackSpeed: 1,
+                    });
+                }
+            }
+            if (childLayers.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: No valid child layers could be created' }],
+                };
+            }
+            // Build padding
+            const uniformPadding = params.padding ?? 0;
+            const groupPadding = {
+                top: params.paddingTop ?? uniformPadding,
+                right: params.paddingRight ?? uniformPadding,
+                bottom: params.paddingBottom ?? uniformPadding,
+                left: params.paddingLeft ?? uniformPadding,
+            };
+            const layoutMode = params.layoutMode || 'column';
+            const widthMode = params.widthMode ?? (params.width !== undefined ? 'fixed' : 'hug');
+            const heightMode = params.heightMode ?? (params.height !== undefined ? 'fixed' : 'hug');
+            const baseWidth = params.width ?? 0.6;
+            const baseHeight = params.height ?? 0.4;
+            const groupLayer = {
+                id: groupId,
+                type: 'group',
+                name: params.name || 'Group',
+                visible: true,
+                locked: false,
+                transform: {
+                    x: params.x ?? 0,
+                    y: params.y ?? 0,
+                    width: 1,
+                    height: 1,
+                    rotation: params.rotation ?? 0,
+                    opacity: params.opacity ?? 1,
+                },
+                children: childLayers,
+                expanded: true,
+                baseWidth,
+                baseHeight,
+                layoutMode,
+                widthMode,
+                heightMode,
+                gap: params.gap ?? 0.02,
+                justifyContent: params.justifyContent ?? 'start',
+                alignItems: params.alignItems ?? 'center',
+                wrap: params.wrap ?? false,
+                padding: groupPadding,
+                ...(params.fillColor ? { fillColor: params.fillColor } : {}),
+                ...(params.fillOpacity !== undefined ? { fillOpacity: params.fillOpacity } : {}),
+                ...(params.cornerRadius !== undefined ? { cornerRadius: params.cornerRadius } : {}),
+            };
+            currentPoster.layers.push(groupLayer);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Group added with ${childLayers.length} children (${groupLayer.layoutMode} layout)`,
+                            group: groupLayer,
+                            totalLayers: currentPoster.layers.length,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         case 'modify_layer': {
             if (!currentPoster) {
                 return {
@@ -962,6 +1432,22 @@ async function handleStateTool(name, args) {
                     textLayer.letterSpacing = params.letterSpacing;
                 if (params.lineHeight !== undefined)
                     textLayer.lineHeight = params.lineHeight;
+                // Reconcile textType (canonical) vs textTransformMode (legacy). textType wins.
+                if (params.textType !== undefined || params.textTransformMode !== undefined) {
+                    const resolvedTextType = params.textType !== undefined
+                        ? params.textType
+                        : (params.textTransformMode === 'scale' ? 'point' : 'frame');
+                    textLayer.textType = resolvedTextType;
+                    textLayer.textTransformMode = resolvedTextType === 'point' ? 'scale' : 'box';
+                }
+                if (params.textBoxWidth !== undefined)
+                    textLayer.textBoxWidth = params.textBoxWidth;
+                if (params.frameWidthPx !== undefined)
+                    textLayer.frameWidthPx = params.frameWidthPx;
+                if (params.frameHeightPx !== undefined)
+                    textLayer.frameHeightPx = params.frameHeightPx;
+                if (params.autoSize !== undefined)
+                    textLayer.autoSize = params.autoSize;
                 // Update animation settings
                 if (params.animationType !== undefined) {
                     if (params.animationType === 'none') {
@@ -1095,6 +1581,54 @@ async function handleStateTool(name, args) {
                 if (params.objectFit !== undefined)
                     mediaLayer.objectFit = params.objectFit;
             }
+            // Update group layout properties
+            if (layer.type === 'group') {
+                const groupLayer = layer;
+                if (params.layoutMode !== undefined)
+                    groupLayer.layoutMode = params.layoutMode;
+                if (params.widthMode !== undefined)
+                    groupLayer.widthMode = params.widthMode;
+                if (params.heightMode !== undefined)
+                    groupLayer.heightMode = params.heightMode;
+                if (params.gap !== undefined)
+                    groupLayer.gap = params.gap;
+                if (params.justifyContent !== undefined)
+                    groupLayer.justifyContent = params.justifyContent;
+                if (params.alignItems !== undefined)
+                    groupLayer.alignItems = params.alignItems;
+                if (params.wrap !== undefined)
+                    groupLayer.wrap = params.wrap;
+                if (params.fillColor !== undefined)
+                    groupLayer.fillColor = params.fillColor;
+                if (params.fillOpacity !== undefined)
+                    groupLayer.fillOpacity = params.fillOpacity;
+                if (params.cornerRadius !== undefined)
+                    groupLayer.cornerRadius = params.cornerRadius;
+                // Padding: uniform or individual overrides
+                if (params.padding !== undefined || params.paddingTop !== undefined || params.paddingRight !== undefined || params.paddingBottom !== undefined || params.paddingLeft !== undefined) {
+                    const existing = groupLayer.padding || { top: 0, right: 0, bottom: 0, left: 0 };
+                    const uniform = params.padding ?? undefined;
+                    groupLayer.padding = {
+                        top: params.paddingTop ?? uniform ?? existing.top,
+                        right: params.paddingRight ?? uniform ?? existing.right,
+                        bottom: params.paddingBottom ?? uniform ?? existing.bottom,
+                        left: params.paddingLeft ?? uniform ?? existing.left,
+                    };
+                }
+                // Allow updating baseWidth/baseHeight via width/height params
+                if (params.width !== undefined) {
+                    groupLayer.baseWidth = params.width;
+                    if (params.widthMode === undefined) {
+                        groupLayer.widthMode = 'fixed';
+                    }
+                }
+                if (params.height !== undefined) {
+                    groupLayer.baseHeight = params.height;
+                    if (params.heightMode === undefined) {
+                        groupLayer.heightMode = 'fixed';
+                    }
+                }
+            }
             return {
                 content: [
                     {
@@ -1250,12 +1784,12 @@ async function handleStateTool(name, args) {
             }
             else if (settingsKey === 'chromatic') {
                 effect.chromatic = {
-                    shape: 'dot',
+                    shape: 'square',
                     radius: 4,
                     rotateR: 15,
                     rotateG: 75,
                     rotateB: 0,
-                    scatter: 0,
+                    scatter: 1,
                     blending: 1,
                     blendingMode: 'linear',
                     greyscale: false,
@@ -1273,12 +1807,12 @@ async function handleStateTool(name, args) {
                     // Digital glitch defaults
                     blockSize: 0.5,
                     displacement: 0.5,
-                    blockOpacity: 1.0,
+                    blockOpacity: 0,
                     colorSplit: 0.5,
                     lineTear: 0.5,
                     pixelate: 0.3,
                     // Weird glitch defaults
-                    glitchChance: 0.2,
+                    glitchChance: 0.66,
                     glitchSpeed: 7.0,
                     sliceDensity: 14.0,
                     sliceStrength: 0.38,