@efectoapp/mcp-server 0.1.19 → 0.1.22

package/dist/tools/state.js

@@ -14,9 +14,13 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stateTools = void 0;
+exports.ensurePoster = ensurePoster;
 exports.resetState = resetState;
 exports.getCurrentState = getCurrentState;
 exports.handleStateTool = handleStateTool;
+const os_1 = require("os");
+const fs_1 = require("fs");
+const path_1 = require("path");
 // Helper to clamp values to valid ranges
 function clamp(value, min, max, fallback) {
     const v = value ?? fallback;
@@ -24,6 +28,335 @@ function clamp(value, min, max, fallback) {
         return fallback;
     return Math.min(max, Math.max(min, v));
 }
+function parseNumericInput(input) {
+    if (typeof input === 'number' && Number.isFinite(input))
+        return input;
+    if (typeof input === 'string') {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return undefined;
+        const stripped = trimmed.endsWith('%') ? trimmed.slice(0, -1) : trimmed;
+        const parsed = Number.parseFloat(stripped);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * Palette color lookup map — mirrors lib/color-palettes.ts COLOR_PALETTES.
+ * When a paletteId is provided, we resolve it to actual hex colors so the
+ * colors array is always in sync and URL-encoded state renders correctly.
+ */
+const PALETTE_COLORS = {
+    // Classic 2-color
+    noir: ['#000000', '#ffffff'],
+    ink: ['#1a1a2e', '#f5f5dc'],
+    terminal: ['#001100', '#00ff00'],
+    'amber-glow': ['#1a0f00', '#ffcc00'],
+    // Retro gaming
+    gameboy: ['#0f380f', '#306230', '#8bac0f', '#9bbc0f'],
+    commodore: ['#000000', '#6c5eb5', '#959595', '#ffffff'],
+    nes: ['#000000', '#b53120', '#6b6b6b', '#fcfcfc'],
+    cga: ['#000000', '#aa00aa', '#00aaaa', '#ffffff'],
+    // Warm
+    'sunset-blvd': ['#1a1423', '#4a1942', '#b33951', '#f5a962', '#fff4e0'],
+    campfire: ['#1a0a0a', '#4a0e0e', '#8b1a1a', '#d44d1a', '#ffcc00'],
+    'autumn-leaves': ['#2d1b0e', '#6b3e26', '#b5651d', '#e09f3e', '#f5deb3'],
+    terracotta: ['#1f1410', '#5c3d2e', '#b36b4f', '#e8a87c', '#faf0e6'],
+    'golden-hour': ['#1a1205', '#4a3510', '#8b6914', '#d4a017', '#fff8dc'],
+    'rose-gold': ['#2a1a1a', '#6b4040', '#b76e79', '#e8b4bc', '#fff0f5'],
+    // Cool
+    'deep-sea': ['#0a1628', '#1a3a5c', '#2d6187', '#5ba4c9', '#a8dce8'],
+    'arctic-night': ['#0a0a14', '#1a2a4a', '#3a5a8a', '#6a9aca', '#cae8ff'],
+    moonlight: ['#0f0f1a', '#2a2a4a', '#4a4a7a', '#8a8ab0', '#e0e0f0'],
+    frozen: ['#1a1a2e', '#16213e', '#0f3460', '#53a8b6', '#e8f1f5'],
+    twilight: ['#0d0221', '#261447', '#4a2c6a', '#7a4a9a', '#c8a8e8'],
+    // Neon
+    synthwave: ['#120458', '#7b2cbf', '#e040fb', '#ff6ec7', '#fff59d'],
+    vaporwave: ['#1a0a2e', '#3d1a5c', '#ff71ce', '#01cdfe', '#fffb96'],
+    cyberpunk: ['#0d0221', '#261447', '#6b2d5c', '#f72585', '#4cc9f0'],
+    'tokyo-night': ['#1a1b26', '#414868', '#7aa2f7', '#bb9af7', '#c0caf5'],
+    arcade: ['#0d0d0d', '#ff073a', '#39ff14', '#00f0ff', '#ffffff'],
+    retrowave: ['#2b1055', '#7f00ff', '#e100ff', '#ff5c8d', '#ffd700'],
+    electric: ['#0a0a0a', '#0066ff', '#00ffff', '#ff00ff', '#ffffff'],
+    // Earth
+    forest: ['#1a2e1a', '#2d4a2d', '#4a7c4a', '#7ab37a', '#c8e6c8'],
+    moss: ['#1a1f14', '#3d4a2d', '#6b7b4a', '#a8b88a', '#d4e4bc'],
+    desert: ['#2e1f14', '#6b4423', '#c19a6b', '#e6c89c', '#f5e6d3'],
+    clay: ['#2a1810', '#5a3828', '#9a6848', '#d4a878', '#f4e4d4'],
+    'ocean-floor': ['#0a1a1a', '#1a3a3a', '#2a6a5a', '#4a9a7a', '#8adaaa'],
+    // Mono
+    grayscale: ['#000000', '#404040', '#808080', '#c0c0c0', '#ffffff'],
+    sepia: ['#1a1610', '#3d3020', '#6b5a40', '#a89070', '#e8dcc8'],
+    blueprint: ['#001830', '#003060', '#0050a0', '#0080e0', '#e0f0ff'],
+    cyanotype: ['#001a2e', '#003050', '#005080', '#0080b0', '#a0d8f0'],
+    'green-phosphor': ['#001400', '#003300', '#006600', '#00cc00', '#66ff66'],
+    'amber-phosphor': ['#1a0f00', '#3d2400', '#7a4800', '#cc7a00', '#ffcc66'],
+};
+/** Resolve a paletteId to its colors, falling back to the provided default. */
+function resolvePaletteColors(paletteId, fallback) {
+    if (!paletteId)
+        return fallback;
+    return PALETTE_COLORS[paletteId] ?? fallback;
+}
+const TEXT_WORLD_SCALE_FACTOR = 0.15 / 72;
+function getArtboardAspect(aspectRatio) {
+    switch (aspectRatio) {
+        case '16:9':
+            return 16 / 9;
+        case '9:16':
+            return 9 / 16;
+        case '1:1':
+            return 1;
+        case '4:3':
+            return 4 / 3;
+        case '3:4':
+            return 3 / 4;
+        default:
+            return 9 / 16;
+    }
+}
+function parseNormalizedFrameDimension(input) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return undefined;
+    if (!Number.isFinite(value))
+        return undefined;
+    return clamp(value, 0.01, 2, value);
+}
+function textNormalizedToPx(normalized, artboardAspect, axis) {
+    if (axis === 'height') {
+        return normalized / TEXT_WORLD_SCALE_FACTOR;
+    }
+    return (normalized * artboardAspect) / TEXT_WORLD_SCALE_FACTOR;
+}
+/** Convert CSS-style % from left (0=left, 50=center, 100=right) to normalized x (-1..1). */
+function cssPercentToX(input, fallbackPct = 50) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return (fallbackPct / 50) - 1;
+    // Always interpret as CSS percentage from left edge
+    const pct = Math.max(-50, Math.min(150, value));
+    return (pct / 50) - 1; // 0→-1, 50→0, 100→1
+}
+/** Convert CSS-style % from top (0=top, 50=center, 100=bottom) to normalized y (-1..1, +up). */
+function cssPercentToY(input, fallbackPct = 50) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return 1 - (fallbackPct / 50);
+    // Always interpret as CSS percentage from top edge
+    const pct = Math.max(-50, Math.min(150, value));
+    return 1 - (pct / 50); // 0→1(top), 50→0(center), 100→-1(bottom)
+}
+/** Convert CSS-style % size (60=60%) to normalized size (0.6).
+ *  Values 0-1 pass through for backward compat. */
+function cssPercentToSize(input, fallbackPct = 100) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return fallbackPct / 100;
+    // Values > 1 are treated as %, values 0-1 pass through
+    const normalized = value > 1 && value <= 200 ? value / 100 : value;
+    return clamp(normalized, 0.01, 4, normalized);
+}
+function normalizeOpacity(input, fallback) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return fallback;
+    const normalized = value > 1 && value <= 100 ? value / 100 : value;
+    return clamp(normalized, 0, 1, fallback);
+}
+function normalizeStrokeWidth(input, fallback) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return fallback;
+    const normalized = value > 1 ? value / 1000 : value;
+    return clamp(normalized, 0, 0.2, fallback);
+}
+function normalizeCornerRadius(input, fallback) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return fallback;
+    const normalized = value > 1 ? value / 1000 : value;
+    return clamp(normalized, 0, 1, fallback);
+}
+function normalizePositiveInt(input, fallback, min, max) {
+    const value = parseNumericInput(input);
+    if (value === undefined)
+        return fallback;
+    const rounded = Math.round(value);
+    return Math.min(max, Math.max(min, rounded));
+}
+function parseFlexChildProps(input) {
+    const result = {};
+    if (typeof input.positioning === 'string') {
+        const v = input.positioning.trim().toLowerCase();
+        if (v === 'flow' || v === 'absolute')
+            result.positioning = v;
+    }
+    // Per-axis sizing (preferred)
+    if (typeof input.flexWidthMode === 'string') {
+        const v = input.flexWidthMode.trim().toLowerCase();
+        if (v === 'hug' || v === 'fixed' || v === 'fill')
+            result.flexWidthMode = v;
+    }
+    if (typeof input.flexHeightMode === 'string') {
+        const v = input.flexHeightMode.trim().toLowerCase();
+        if (v === 'hug' || v === 'fixed' || v === 'fill')
+            result.flexHeightMode = v;
+    }
+    // Legacy single-axis: applies to both axes if per-axis not set
+    if (typeof input.flexSizeMode === 'string') {
+        const v = input.flexSizeMode.trim().toLowerCase();
+        if (v === 'hug' || v === 'fixed' || v === 'fill') {
+            if (!result.flexWidthMode)
+                result.flexWidthMode = v;
+            if (!result.flexHeightMode)
+                result.flexHeightMode = v;
+        }
+    }
+    if (typeof input.alignSelf === 'string') {
+        const v = input.alignSelf.trim().toLowerCase();
+        if (v === 'auto' || v === 'start' || v === 'center' || v === 'end' || v === 'stretch')
+            result.alignSelf = v;
+    }
+    if (input.flexGrow !== undefined) {
+        const val = Number(input.flexGrow);
+        if (Number.isFinite(val) && val >= 0)
+            result.flexGrow = val;
+    }
+    return result;
+}
+// --- Visual property parsers (shadow, blendMode, textTransform, textDecoration) ---
+const VALID_TEXT_TRANSFORMS = ['none', 'uppercase', 'lowercase', 'capitalize'];
+const VALID_TEXT_DECORATIONS = ['none', 'underline', 'line-through', 'overline'];
+const VALID_BLEND_MODES = ['normal', 'multiply', 'screen', 'darken', 'lighten', 'difference'];
+function parseShadowParams(params) {
+    const hasShadow = params.shadowOffsetX !== undefined || params.shadowOffsetY !== undefined ||
+        params.shadowBlur !== undefined || params.shadowColor !== undefined;
+    if (!hasShadow)
+        return undefined;
+    return {
+        offsetX: typeof params.shadowOffsetX === 'number' ? params.shadowOffsetX : 0,
+        offsetY: typeof params.shadowOffsetY === 'number' ? params.shadowOffsetY : 4,
+        blur: typeof params.shadowBlur === 'number' ? Math.max(0, params.shadowBlur) : 8,
+        color: normalizeHexColor(params.shadowColor) || '#000000',
+        opacity: typeof params.shadowOpacity === 'number' ? Math.max(0, Math.min(1, params.shadowOpacity)) : 0.5,
+    };
+}
+function parseBlendMode(params) {
+    const mode = params.blendMode;
+    if (!mode || !VALID_BLEND_MODES.includes(mode))
+        return undefined;
+    if (mode === 'normal')
+        return undefined; // Don't store default
+    return mode;
+}
+function parseTextTransform(params) {
+    const val = params.textTransform;
+    if (!val || !VALID_TEXT_TRANSFORMS.includes(val))
+        return undefined;
+    if (val === 'none')
+        return undefined;
+    return val;
+}
+function parseTextDecoration(params) {
+    const result = {};
+    const val = params.textDecoration;
+    if (val && VALID_TEXT_DECORATIONS.includes(val) && val !== 'none') {
+        result.textDecoration = val;
+    }
+    if (params.textDecorationColor !== undefined) {
+        const color = normalizeHexColor(params.textDecorationColor);
+        if (color)
+            result.textDecorationColor = color;
+    }
+    if (typeof params.textDecorationThickness === 'number' && params.textDecorationThickness > 0) {
+        result.textDecorationThickness = params.textDecorationThickness;
+    }
+    return result;
+}
+/** Parse margin params */
+function parseMarginParams(params) {
+    const hasMargin = params.marginTop !== undefined || params.marginRight !== undefined ||
+        params.marginBottom !== undefined || params.marginLeft !== undefined;
+    if (!hasMargin)
+        return undefined;
+    return {
+        top: typeof params.marginTop === 'number' ? params.marginTop : 0,
+        right: typeof params.marginRight === 'number' ? params.marginRight : 0,
+        bottom: typeof params.marginBottom === 'number' ? params.marginBottom : 0,
+        left: typeof params.marginLeft === 'number' ? params.marginLeft : 0,
+    };
+}
+/** Parse min/max size constraint params */
+function parseMinMaxConstraints(params) {
+    const result = {};
+    if (typeof params.minWidth === 'number')
+        result.minWidth = Math.max(0, Math.min(1, params.minWidth));
+    if (typeof params.maxWidth === 'number')
+        result.maxWidth = Math.max(0, Math.min(1, params.maxWidth));
+    if (typeof params.minHeight === 'number')
+        result.minHeight = Math.max(0, Math.min(1, params.minHeight));
+    if (typeof params.maxHeight === 'number')
+        result.maxHeight = Math.max(0, Math.min(1, params.maxHeight));
+    return result;
+}
+/** Parse per-corner radius params */
+function parseCornerRadii(params) {
+    const hasPerCorner = params.cornerRadiusTopLeft !== undefined || params.cornerRadiusTopRight !== undefined ||
+        params.cornerRadiusBottomRight !== undefined || params.cornerRadiusBottomLeft !== undefined;
+    if (!hasPerCorner)
+        return undefined;
+    return {
+        topLeft: typeof params.cornerRadiusTopLeft === 'number' ? Math.max(0, params.cornerRadiusTopLeft) : 0,
+        topRight: typeof params.cornerRadiusTopRight === 'number' ? Math.max(0, params.cornerRadiusTopRight) : 0,
+        bottomRight: typeof params.cornerRadiusBottomRight === 'number' ? Math.max(0, params.cornerRadiusBottomRight) : 0,
+        bottomLeft: typeof params.cornerRadiusBottomLeft === 'number' ? Math.max(0, params.cornerRadiusBottomLeft) : 0,
+    };
+}
+/** Parse transform origin params */
+function parseTransformOrigin(params) {
+    const result = {};
+    if (typeof params.originX === 'number')
+        result.originX = Math.max(0, Math.min(1, params.originX));
+    if (typeof params.originY === 'number')
+        result.originY = Math.max(0, Math.min(1, params.originY));
+    return result;
+}
+/** Parse visual properties shared across all layer types (shadow, blendMode, margin, min/max constraints) */
+function parseVisualOverrides(params) {
+    const result = {};
+    const shadow = parseShadowParams(params);
+    if (shadow)
+        result.shadow = shadow;
+    const blendMode = parseBlendMode(params);
+    if (blendMode)
+        result.blendMode = blendMode;
+    const margin = parseMarginParams(params);
+    if (margin)
+        result.margin = margin;
+    const constraints = parseMinMaxConstraints(params);
+    Object.assign(result, constraints);
+    return result;
+}
+function normalizeHexColor(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const withHash = trimmed.startsWith('#') ? trimmed : `#${trimmed}`;
+    if (/^#[0-9a-f]{6}$/i.test(withHash))
+        return withHash.toLowerCase();
+    if (/^#[0-9a-f]{3}$/i.test(withHash)) {
+        const [, r, g, b] = withHash;
+        return `#${r}${r}${g}${g}${b}${b}`.toLowerCase();
+    }
+    return null;
+}
+function asFiniteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
 // Known fonts with their proper CSS values
 const KNOWN_FONTS = {
     'DM Sans': '"DM Sans", sans-serif',
@@ -66,9 +399,75 @@ function normalizeFontFamily(input) {
 }
 // Current poster state (single poster for now)
 let currentPoster = null;
+// --- File-based state persistence ---
+// Some MCP clients spawn a fresh process per tool call, losing in-memory state.
+// We persist to a temp file so state survives process restarts.
+const STATE_FILE_PATH = (0, path_1.join)((0, os_1.tmpdir)(), 'efecto-mcp-state.json');
+const STATE_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+/** Write current poster state to the temp file (best-effort). */
+function persistState() {
+    if (!currentPoster)
+        return;
+    try {
+        const payload = JSON.stringify({ timestamp: Date.now(), state: currentPoster });
+        (0, fs_1.writeFileSync)(STATE_FILE_PATH, payload, 'utf-8');
+    }
+    catch {
+        // Silently ignore — falls back to in-memory only
+    }
+}
+/** Load persisted state from the temp file if valid and not stale. */
+function loadPersistedState() {
+    try {
+        const raw = (0, fs_1.readFileSync)(STATE_FILE_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.state || !parsed.timestamp)
+            return null;
+        if (Date.now() - parsed.timestamp > STATE_MAX_AGE_MS)
+            return null;
+        return parsed.state;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure a poster exists. Restores from persisted file if needed,
+ * or auto-creates a default poster as a last resort.
+ */
+function ensurePoster() {
+    if (currentPoster)
+        return currentPoster;
+    // Try restoring from persisted state
+    const persisted = loadPersistedState();
+    if (persisted) {
+        currentPoster = persisted;
+        return currentPoster;
+    }
+    // Auto-create a default poster (same defaults as create_poster)
+    currentPoster = {
+        canvas: {
+            aspectRatio: '9:16',
+            backgroundColor: '#1a1a1a',
+            layoutMode: 'column',
+            alignItems: 'center',
+            justifyContent: 'start',
+            gap: 0.04,
+            padding: { top: 0.08, right: 0.08, bottom: 0.08, left: 0.08 },
+        },
+        layers: [createDefaultBackgroundLayer('#1a1a1a')],
+        postProcesses: [],
+    };
+    persistState();
+    return currentPoster;
+}
 // Reset state (useful for testing)
 function resetState() {
     currentPoster = null;
+    try {
+        (0, fs_1.unlinkSync)(STATE_FILE_PATH);
+    }
+    catch { /* ignore */ }
 }
 // Get current state
 function getCurrentState() {
@@ -85,7 +484,7 @@ function getDefaultAnimationParams(type) {
     const base = {
         type,
         enabled: true,
-        speed: 1.0,
+        speed: 0.2,
         amplitude: 50,
         staggerDelay: 150,
         staggerMode: 'sequential',
@@ -289,8 +688,225 @@ 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;
+}
+/**
+ * Build a Fill object from flat MCP tool params (fillType, gradientStops, etc.).
+ * Returns null when no gradient params are present (caller should fall back to solid).
+ */
+function buildFillFromParams(params) {
+    const fillType = params.fillType;
+    const hasGradientParams = fillType === 'linear' || fillType === 'radial' ||
+        params.gradientStyle !== undefined ||
+        params.gradientStops !== undefined ||
+        params.gradientStartColor !== undefined ||
+        params.gradientEndColor !== undefined;
+    if (!hasGradientParams)
+        return null;
+    const gradientStyle = fillType === 'radial' || params.gradientStyle === 'radial' ? 'radial' : 'linear';
+    const defaults = gradientStyle === 'radial'
+        ? DEFAULT_RADIAL_GRADIENT_FILL
+        : DEFAULT_LINEAR_GRADIENT_FILL;
+    const explicitStops = parseGradientStopsInput(params.gradientStops, defaults.stops);
+    const stops = explicitStops ?? [
+        {
+            color: params.gradientStartColor || defaults.stops[0].color,
+            opacity: defaults.stops[0].opacity,
+            position: defaults.stops[0].position,
+        },
+        {
+            color: params.gradientEndColor || defaults.stops[1].color,
+            opacity: defaults.stops[1].opacity,
+            position: defaults.stops[1].position,
+        },
+    ];
+    if (gradientStyle === 'radial') {
+        return 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,
+        });
+    }
+    return normalizeLinearGradientFill({
+        type: 'linear',
+        angle: Number.isFinite(params.gradientAngle)
+            ? params.gradientAngle
+            : DEFAULT_LINEAR_GRADIENT_FILL.angle,
+        stops,
+    });
+}
+/** Reusable schema properties for gradient fill params — spread into tool schemas. */
+const GRADIENT_FILL_SCHEMA_PROPS = {
+    fillType: {
+        type: 'string',
+        enum: ['solid', 'linear', 'radial'],
+        description: 'Fill type: "solid" (default), "linear" gradient, or "radial" gradient',
+    },
+    gradientStops: {
+        type: 'array',
+        description: 'Gradient color stops (2-8). Overrides start/end colors when provided.',
+        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,
+    },
+    gradientAngle: {
+        type: 'number',
+        description: 'Linear gradient angle in degrees (default 135)',
+    },
+    gradientStartColor: {
+        type: 'string',
+        description: 'Gradient start color in hex (shortcut for 2-stop gradient)',
+    },
+    gradientEndColor: {
+        type: 'string',
+        description: 'Gradient end color in hex (shortcut for 2-stop gradient)',
+    },
+    gradientStyle: {
+        type: 'string',
+        enum: ['linear', 'radial'],
+        description: 'Gradient style (alternative to fillType for setting gradient type)',
+    },
+    gradientCenterX: {
+        type: 'number',
+        description: 'Radial gradient center X (0-1)',
+    },
+    gradientCenterY: {
+        type: 'number',
+        description: 'Radial gradient center Y (0-1)',
+    },
+    gradientRadius: {
+        type: 'number',
+        description: 'Radial gradient radius (0.05-2)',
+    },
+};
 // Tool definitions
 exports.stateTools = [
     {
@@ -301,7 +917,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',
                 },
@@ -310,19 +926,97 @@ exports.stateTools = [
                     description: 'Background color in hex format (e.g., "#1a1a1a")',
                     default: '#1a1a1a',
                 },
+                canvasColor: {
+                    type: 'string',
+                    description: 'Viewport background color in hex (e.g., "#0a0a0a")',
+                },
+                overflow: {
+                    type: 'string',
+                    enum: ['visible', 'hidden', 'translucent'],
+                    description: 'Canvas overflow mode',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'clear_poster',
+        description: 'Clear all content layers from the poster, keeping only the background. Resets effect and post-processes.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'set_page_layout',
+        description: 'Set page/artboard layout mode. Use layoutMode="absolute" for Free placement. Use layoutMode="row" or "column" for Flex layout of top-level layers inside the artboard.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layoutMode: {
+                    type: 'string',
+                    enum: ['absolute', 'row', 'column'],
+                    description: 'Page layout mode: "absolute" (Free) or flex direction ("row"/"column")',
+                },
+                justifyContent: {
+                    type: 'string',
+                    enum: ['start', 'center', 'end', 'space-between', 'space-around', 'space-evenly'],
+                    description: 'Main axis alignment (flex only)',
+                },
+                alignItems: {
+                    type: 'string',
+                    enum: ['start', 'center', 'end'],
+                    description: 'Cross axis alignment (flex only)',
+                },
+                wrap: { type: 'boolean', description: 'Wrap to next row (row mode only)', default: false },
+                gap: { type: 'number', description: 'Space between children as % of canvas (2=small, 4=medium, 6=large)', default: 0 },
+                padding: { type: 'number', description: 'Padding as % of canvas', default: 0 },
+                paddingTop: { type: 'number', description: 'Padding top as % of canvas' },
+                paddingRight: { type: 'number', description: 'Padding right as % of canvas' },
+                paddingBottom: { type: 'number', description: 'Padding bottom as % of canvas' },
+                paddingLeft: { type: 'number', description: 'Padding left as % of canvas' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'modify_canvas',
+        description: 'Modify the canvas/artboard settings after creation. Change aspect ratio, background color, viewport color, or overflow mode.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                aspectRatio: {
+                    type: 'string',
+                    enum: ['16:9', '9:16', '1:1', '4:3', '3:4', 'full'],
+                    description: 'Canvas aspect ratio',
+                },
+                backgroundColor: {
+                    type: 'string',
+                    description: 'Artboard background color in hex (e.g., "#1a1a1a")',
+                },
+                canvasColor: {
+                    type: 'string',
+                    description: 'Viewport background color in hex (area outside artboard)',
+                },
+                overflow: {
+                    type: 'string',
+                    enum: ['visible', 'hidden', 'translucent'],
+                    description: 'Canvas overflow mode',
+                },
             },
             required: [],
         },
     },
     {
         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 +1024,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)',
@@ -356,26 +1094,66 @@ exports.stateTools = [
             properties: {
                 type: {
                     type: 'string',
-                    enum: ['text', 'image', 'video'],
+                    enum: ['text', 'image', 'video', 'rectangle', 'ellipse', 'polygon', 'star', 'line'],
                     description: 'Type of layer to add',
                 },
                 name: { type: 'string', description: 'Layer name' },
                 // Transform properties (normalized coordinates relative to canvas)
-                x: { type: 'number', description: 'X position (-1 to 1, 0 is center, positive is right)', default: 0 },
-                y: { type: 'number', description: 'Y position (-1 to 1, 0 is center, POSITIVE is UP/TOP, negative is down/bottom)', default: 0 },
-                width: { type: 'number', description: 'Width (0-1 relative to canvas)', default: 1 },
-                height: { type: 'number', description: 'Height (0-1 relative to canvas)', default: 1 },
+                x: { type: 'number', description: 'Horizontal position in % from left (0=left edge, 50=center, 100=right edge)', default: 50 },
+                y: { type: 'number', description: 'Vertical position in % from top (0=top edge, 50=center, 100=bottom edge)', default: 50 },
+                width: { type: 'number', description: 'Width as % of canvas (e.g. 60 = 60%)', default: 100 },
+                height: { type: 'number', description: 'Height as % of canvas', default: 100 },
                 rotation: { type: 'number', description: 'Rotation in degrees', default: 0 },
                 opacity: { type: 'number', description: 'Opacity 0-1', default: 1 },
+                // Flex child properties (when inside a flex group or page-level flex)
+                positioning: { type: 'string', enum: ['flow', 'absolute'], description: 'Child positioning inside flex groups. "absolute" opts out of flow layout.' },
+                flexWidthMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Child width sizing mode inside flex groups (independent per-axis).' },
+                flexHeightMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Child height sizing mode inside flex groups (independent per-axis).' },
+                flexSizeMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Legacy: sets both axes. Prefer flexWidthMode/flexHeightMode.' },
+                alignSelf: { type: 'string', enum: ['auto', 'start', 'center', 'end', 'stretch'], description: 'Child cross-axis alignment override inside flex groups.' },
+                flexGrow: { type: 'number', minimum: 0, description: 'Flex grow factor. Controls how fill children share free space proportionally (like CSS flex-grow). Default 1 for fill children.' },
+                // Shape style properties (rectangle/ellipse/polygon/star/line)
+                fillColor: { type: 'string', description: 'Shape fill color in hex (e.g. #ffffff)' },
+                fillOpacity: { type: 'number', description: 'Shape fill opacity (0-1)' },
+                ...GRADIENT_FILL_SCHEMA_PROPS,
+                strokeColor: { type: 'string', description: 'Shape stroke color in hex' },
+                strokeWidth: { type: 'number', description: 'Shape stroke width (normalized; e.g. 0.005-0.02)' },
+                strokeOpacity: { type: 'number', description: 'Shape stroke opacity (0-1)' },
+                // Rectangle/Polygon/Star geometry
+                cornerRadius: { type: 'number', description: 'Corner radius (normalized)' },
+                // Polygon geometry
+                sides: { type: 'number', description: 'Polygon sides (3+)' },
+                // Star geometry
+                innerRadiusRatio: { type: 'number', description: 'Star inner radius ratio (0-1)' },
+                points: { type: 'number', description: 'Star points (3+)' },
+                // Line geometry (normalized -1..1 coordinates)
+                startX: { type: 'number', description: 'Line start X in % from left (0=left, 50=center, 100=right)' },
+                startY: { type: 'number', description: 'Line start Y in % from top (0=top, 50=center, 100=bottom)' },
+                endX: { type: 'number', description: 'Line end X in % from left (0=left, 50=center, 100=right)' },
+                endY: { type: 'number', description: 'Line end Y in % from top (0=top, 50=center, 100=bottom)' },
                 // Text layer properties
                 content: { type: 'string', description: 'Text content (required for text layers)' },
+                textType: { type: 'string', enum: ['frame'], description: 'Text mode (always "frame" — point text is deprecated)', 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 },
+                verticalAlign: { type: 'string', enum: ['top', 'middle', 'bottom'], description: 'Vertical text alignment inside the frame. Defaults to "top" for frame text.' },
+                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: ['box'], description: 'Text sizing mode (always "box" — scale mode is deprecated)', default: 'box' },
+                textBoxWidth: { type: 'number', description: 'Width in pixels for text wrapping when using box mode (e.g., 300-600 for readable lines)' },
+                frameWidth: { type: 'number', description: 'Frame width normalized (0-1 relative to artboard width). Convenience alias for frameWidthPx.' },
+                frameHeight: { type: 'number', description: 'Frame height normalized (0-1 relative to artboard height). Convenience alias for frameHeightPx.' },
+                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 CSS properties
+                textTransform: { type: 'string', enum: ['none', 'uppercase', 'lowercase', 'capitalize'], description: 'CSS text-transform (visual only, does not mutate stored content)' },
+                textDecoration: { type: 'string', enum: ['none', 'underline', 'line-through', 'overline'], description: 'CSS text-decoration' },
+                textDecorationColor: { type: 'string', description: 'Decoration line color in hex (defaults to text color)' },
+                textDecorationThickness: { type: 'number', description: 'Decoration line thickness in CSS px' },
                 // Text animation properties (use list_text_animations to see all options)
                 animationType: {
                     type: 'string',
@@ -449,36 +1227,204 @@ exports.stateTools = [
                 // Image/Video properties
                 mediaUrl: { type: 'string', description: 'Media URL (required for image/video layers)' },
                 objectFit: { type: 'string', enum: ['cover', 'contain'], description: 'Object fit mode', default: 'cover' },
+                // Shadow properties (all layer types)
+                shadowOffsetX: { type: 'number', description: 'Shadow horizontal offset in CSS px' },
+                shadowOffsetY: { type: 'number', description: 'Shadow vertical offset in CSS px' },
+                shadowBlur: { type: 'number', description: 'Shadow blur radius in CSS px' },
+                shadowColor: { type: 'string', description: 'Shadow color in hex' },
+                shadowOpacity: { type: 'number', description: 'Shadow opacity (0-1)' },
+                // Blend mode (all layer types)
+                blendMode: { type: 'string', enum: ['normal', 'multiply', 'screen', 'darken', 'lighten', 'difference'], description: 'CSS-like blend mode' },
+                // Margin (all layer types, for flex layout spacing)
+                marginTop: { type: 'number', description: 'Margin top (normalized 0-1)' },
+                marginRight: { type: 'number', description: 'Margin right (normalized 0-1)' },
+                marginBottom: { type: 'number', description: 'Margin bottom (normalized 0-1)' },
+                marginLeft: { type: 'number', description: 'Margin left (normalized 0-1)' },
+                // Min/max size constraints (all layer types)
+                minWidth: { type: 'number', description: 'Minimum width (normalized 0-1)' },
+                maxWidth: { type: 'number', description: 'Maximum width (normalized 0-1)' },
+                minHeight: { type: 'number', description: 'Minimum height (normalized 0-1)' },
+                maxHeight: { type: 'number', description: 'Maximum height (normalized 0-1)' },
+                // Transform origin (all layer types)
+                originX: { type: 'number', description: 'Transform origin X (0=left, 0.5=center, 1=right)' },
+                originY: { type: 'number', description: 'Transform origin Y (0=top, 0.5=center, 1=bottom)' },
             },
             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 as % of canvas (2=small, 4=medium, 6=large). Negative values overlap children.', default: 2 },
+                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: 'Padding as % of canvas', default: 0 },
+                paddingTop: { type: 'number', description: 'Padding top as % of canvas' },
+                paddingRight: { type: 'number', description: 'Padding right as % of canvas' },
+                paddingBottom: { type: 'number', description: 'Padding bottom as % of canvas' },
+                paddingLeft: { type: 'number', description: 'Padding left as % of canvas' },
+                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: 'Horizontal position in % from left (0=left edge, 50=center, 100=right edge)', default: 50 },
+                y: { type: 'number', description: 'Vertical position in % from top (0=top edge, 50=center, 100=bottom edge)', default: 50 },
+                width: { type: 'number', description: 'Width as % of canvas (e.g. 60 = 60%)', default: 60 },
+                height: { type: 'number', description: 'Height as % of canvas', default: 40 },
+                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', 'rectangle', 'ellipse', 'polygon', 'star', 'line'], 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' },
+                            verticalAlign: { type: 'string', enum: ['top', 'middle', 'bottom'], description: 'Vertical text alignment inside the frame' },
+                            letterSpacing: { type: 'number', description: 'Letter spacing' },
+                            lineHeight: { type: 'number', description: 'Line height multiplier' },
+                            textType: { type: 'string', enum: ['frame'], description: 'Text mode (always "frame")' },
+                            textTransformMode: { type: 'string', enum: ['box'], description: 'Text sizing mode (always "box")' },
+                            textBoxWidth: { type: 'number', description: 'Width for text wrapping' },
+                            frameWidth: { type: 'number', description: 'Frame width normalized (0-1 relative to artboard width). Convenience alias for frameWidthPx.' },
+                            frameHeight: { type: 'number', description: 'Frame height normalized (0-1 relative to artboard height). Convenience alias for frameHeightPx.' },
+                            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' },
+                            textTransform: { type: 'string', enum: ['none', 'uppercase', 'lowercase', 'capitalize'], description: 'CSS text-transform' },
+                            textDecoration: { type: 'string', enum: ['none', 'underline', 'line-through', 'overline'], description: 'CSS text-decoration' },
+                            textDecorationColor: { type: 'string', description: 'Decoration line color (hex)' },
+                            textDecorationThickness: { type: 'number', description: 'Decoration line thickness in CSS px' },
+                            mediaUrl: { type: 'string', description: 'Media URL (for image/video)' },
+                            objectFit: { type: 'string', enum: ['cover', 'contain'], description: 'Object fit mode' },
+                            width: { type: 'number', description: 'Width as % of canvas (e.g. 60 = 60%)' },
+                            height: { type: 'number', description: 'Height as % of canvas' },
+                            opacity: { type: 'number', description: 'Opacity 0-1' },
+                            // Flex child properties
+                            positioning: { type: 'string', enum: ['flow', 'absolute'], description: 'Child positioning in group flex layout' },
+                            flexWidthMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Child width sizing in group flex layout' },
+                            flexHeightMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Child height sizing in group flex layout' },
+                            flexSizeMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Legacy: sets both axes. Prefer flexWidthMode/flexHeightMode.' },
+                            alignSelf: { type: 'string', enum: ['auto', 'start', 'center', 'end', 'stretch'], description: 'Child cross-axis alignment override in group flex layout' },
+                            flexGrow: { type: 'number', minimum: 0, description: 'Flex grow factor for proportional space distribution (like CSS flex-grow). Default 1 for fill children.' },
+                            // Shape style
+                            fillColor: { type: 'string', description: 'Shape fill color (hex)' },
+                            fillOpacity: { type: 'number', description: 'Shape fill opacity (0-1)' },
+                            ...GRADIENT_FILL_SCHEMA_PROPS,
+                            strokeColor: { type: 'string', description: 'Shape stroke color (hex)' },
+                            strokeWidth: { type: 'number', description: 'Shape stroke width (normalized; e.g. 0.005-0.02)' },
+                            strokeOpacity: { type: 'number', description: 'Shape stroke opacity (0-1)' },
+                            // Shape geometry
+                            cornerRadius: { type: 'number', description: 'Corner radius (normalized)' },
+                            sides: { type: 'number', description: 'Polygon sides (3+)' },
+                            innerRadiusRatio: { type: 'number', description: 'Star inner radius ratio (0-1)' },
+                            points: { type: 'number', description: 'Star points (3+)' },
+                            startX: { type: 'number', description: 'Line start X in % from left (0=left, 50=center, 100=right)' },
+                            startY: { type: 'number', description: 'Line start Y in % from top (0=top, 50=center, 100=bottom)' },
+                            endX: { type: 'number', description: 'Line end X in % from left (0=left, 50=center, 100=right)' },
+                            endY: { type: 'number', description: 'Line end Y in % from top (0=top, 50=center, 100=bottom)' },
+                            // Shadow (all layer types)
+                            shadowOffsetX: { type: 'number', description: 'Shadow horizontal offset in CSS px' },
+                            shadowOffsetY: { type: 'number', description: 'Shadow vertical offset in CSS px' },
+                            shadowBlur: { type: 'number', description: 'Shadow blur radius in CSS px' },
+                            shadowColor: { type: 'string', description: 'Shadow color in hex' },
+                            shadowOpacity: { type: 'number', description: 'Shadow opacity (0-1)' },
+                            blendMode: { type: 'string', enum: ['normal', 'multiply', 'screen', 'darken', 'lighten', 'difference'], description: 'CSS-like blend mode' },
+                            marginTop: { type: 'number', description: 'Margin top (normalized 0-1)' },
+                            marginRight: { type: 'number', description: 'Margin right (normalized 0-1)' },
+                            marginBottom: { type: 'number', description: 'Margin bottom (normalized 0-1)' },
+                            marginLeft: { type: 'number', description: 'Margin left (normalized 0-1)' },
+                            minWidth: { type: 'number', description: 'Minimum width (normalized 0-1)' },
+                            maxWidth: { type: 'number', description: 'Maximum width (normalized 0-1)' },
+                            minHeight: { type: 'number', description: 'Minimum height (normalized 0-1)' },
+                            maxHeight: { type: 'number', description: 'Maximum height (normalized 0-1)' },
+                            originX: { type: 'number', description: 'Transform origin X (0=left, 0.5=center, 1=right)' },
+                            originY: { type: 'number', description: 'Transform origin Y (0=top, 0.5=center, 1=bottom)' },
+                            cornerRadiusTopLeft: { type: 'number', description: 'Per-corner radius: top-left (for rectangle layers)' },
+                            cornerRadiusTopRight: { type: 'number', description: 'Per-corner radius: top-right (for rectangle layers)' },
+                            cornerRadiusBottomRight: { type: 'number', description: 'Per-corner radius: bottom-right (for rectangle layers)' },
+                            cornerRadiusBottomLeft: { type: 'number', description: 'Per-corner radius: bottom-left (for rectangle layers)' },
+                        },
+                        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, group, and shape properties.',
         inputSchema: {
             type: 'object',
             properties: {
                 layerId: { type: 'string', description: 'ID of the layer to modify' },
-                // Transform properties (positive Y is UP/TOP, negative Y is down/bottom)
-                x: { type: 'number', description: 'X position (-1 to 1, 0 is center)' },
-                y: { type: 'number', description: 'Y position (-1 to 1, POSITIVE is UP/TOP, negative is down/bottom)' },
-                width: { type: 'number', description: 'Width' },
-                height: { type: 'number', description: 'Height' },
+                // Transform properties (CSS % coordinates)
+                x: { type: 'number', description: 'Horizontal position in % from left (0=left edge, 50=center, 100=right edge)' },
+                y: { type: 'number', description: 'Vertical position in % from top (0=top edge, 50=center, 100=bottom edge)' },
+                width: { type: 'number', description: 'Width as % of canvas (e.g. 60 = 60%)' },
+                height: { type: 'number', description: 'Height as % of canvas' },
                 rotation: { type: 'number', description: 'Rotation in degrees' },
                 opacity: { type: 'number', description: 'Opacity 0-1' },
                 visible: { type: 'boolean', description: 'Layer visibility' },
                 locked: { type: 'boolean', description: 'Layer lock state' },
                 name: { type: 'string', description: 'Layer name' },
+                // Flex child properties
+                positioning: { type: 'string', enum: ['flow', 'absolute'], description: 'Child positioning mode inside flex groups' },
+                flexWidthMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Child width sizing mode inside flex groups (independent per-axis).' },
+                flexHeightMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Child height sizing mode inside flex groups (independent per-axis).' },
+                flexSizeMode: { type: 'string', enum: ['hug', 'fixed', 'fill'], description: 'Legacy: sets both axes. Prefer flexWidthMode/flexHeightMode.' },
+                alignSelf: { type: 'string', enum: ['auto', 'start', 'center', 'end', 'stretch'], description: 'Child cross-axis alignment override inside flex groups' },
+                flexGrow: { type: 'number', minimum: 0, description: 'Flex grow factor for proportional space distribution (like CSS flex-grow). Default 1 for fill children.' },
+                // Shape style properties (rectangle/ellipse/polygon/star/line)
+                strokeColor: { type: 'string', description: 'Shape stroke color (hex)' },
+                strokeWidth: { type: 'number', description: 'Shape stroke width (normalized; e.g. 0.005-0.02)' },
+                strokeOpacity: { type: 'number', description: 'Shape stroke opacity (0-1)' },
+                // Shape geometry
+                sides: { type: 'number', description: 'Polygon sides (3+)' },
+                innerRadiusRatio: { type: 'number', description: 'Star inner radius ratio (0-1)' },
+                points: { type: 'number', description: 'Star points (3+)' },
+                startX: { type: 'number', description: 'Line start X in % from left (0=left, 50=center, 100=right)' },
+                startY: { type: 'number', description: 'Line start Y in % from top (0=top, 50=center, 100=bottom)' },
+                endX: { type: 'number', description: 'Line end X in % from left (0=left, 50=center, 100=right)' },
+                endY: { type: 'number', description: 'Line end Y in % from top (0=top, 50=center, 100=bottom)' },
                 // Text layer properties
                 content: { type: 'string' },
+                textType: { type: 'string', enum: ['frame'], description: 'Text mode (always "frame")' },
                 fontFamily: { type: 'string' },
                 fontSize: { type: 'number' },
                 fontWeight: { type: 'string' },
                 color: { type: 'string' },
                 textAlign: { type: 'string' },
+                verticalAlign: { type: 'string', enum: ['top', 'middle', 'bottom'], description: 'Vertical text alignment inside the frame' },
                 letterSpacing: { type: 'number' },
                 lineHeight: { type: 'number' },
+                textTransformMode: { type: 'string', enum: ['box'] },
+                textBoxWidth: { type: 'number' },
+                frameWidth: { type: 'number', description: 'Frame width normalized (0-1 relative to artboard width). Convenience alias for frameWidthPx.' },
+                frameHeight: { type: 'number', description: 'Frame height normalized (0-1 relative to artboard height). Convenience alias for frameHeightPx.' },
+                frameWidthPx: { type: 'number' },
+                frameHeightPx: { type: 'number' },
+                autoSize: { type: 'string', enum: ['none', 'height', 'widthAndHeight'] },
+                // Text CSS properties
+                textTransform: { type: 'string', enum: ['none', 'uppercase', 'lowercase', 'capitalize'], description: 'CSS text-transform (visual only, does not mutate stored content)' },
+                textDecoration: { type: 'string', enum: ['none', 'underline', 'line-through', 'overline'], description: 'CSS text-decoration' },
+                textDecorationColor: { type: 'string', description: 'Decoration line color in hex (defaults to text color)' },
+                textDecorationThickness: { type: 'number', description: 'Decoration line thickness in CSS px' },
                 // Text animation properties (all type-specific params supported - see add_layer for descriptions)
                 animationType: {
                     type: 'string',
@@ -535,6 +1481,49 @@ 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: 'Space between children as % of canvas (2=small, 4=medium, 6=large)' },
+                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: 'Padding as % of canvas' },
+                paddingTop: { type: 'number', description: 'Padding top as % of canvas' },
+                paddingRight: { type: 'number', description: 'Padding right as % of canvas' },
+                paddingBottom: { type: 'number', description: 'Padding bottom as % of canvas' },
+                paddingLeft: { type: 'number', description: 'Padding left as % of canvas' },
+                fillColor: { type: 'string', description: 'Fill color (group background OR shape fill)' },
+                fillOpacity: { type: 'number', description: 'Fill opacity (group background OR shape fill)' },
+                ...GRADIENT_FILL_SCHEMA_PROPS,
+                cornerRadius: { type: 'number', description: 'Corner radius (group OR shape)' },
+                // Shadow properties (all layer types)
+                shadowOffsetX: { type: 'number', description: 'Shadow horizontal offset in CSS px' },
+                shadowOffsetY: { type: 'number', description: 'Shadow vertical offset in CSS px' },
+                shadowBlur: { type: 'number', description: 'Shadow blur radius in CSS px' },
+                shadowColor: { type: 'string', description: 'Shadow color in hex' },
+                shadowOpacity: { type: 'number', description: 'Shadow opacity (0-1)' },
+                // Blend mode (all layer types)
+                blendMode: { type: 'string', enum: ['normal', 'multiply', 'screen', 'darken', 'lighten', 'difference'], description: 'CSS-like blend mode' },
+                // Margin (all layer types)
+                marginTop: { type: 'number', description: 'Margin top (normalized 0-1)' },
+                marginRight: { type: 'number', description: 'Margin right (normalized 0-1)' },
+                marginBottom: { type: 'number', description: 'Margin bottom (normalized 0-1)' },
+                marginLeft: { type: 'number', description: 'Margin left (normalized 0-1)' },
+                // Min/max size constraints (all layer types)
+                minWidth: { type: 'number', description: 'Minimum width (normalized 0-1)' },
+                maxWidth: { type: 'number', description: 'Maximum width (normalized 0-1)' },
+                minHeight: { type: 'number', description: 'Minimum height (normalized 0-1)' },
+                maxHeight: { type: 'number', description: 'Maximum height (normalized 0-1)' },
+                // Transform origin (all layer types)
+                originX: { type: 'number', description: 'Transform origin X (0=left, 0.5=center, 1=right)' },
+                originY: { type: 'number', description: 'Transform origin Y (0=top, 0.5=center, 1=bottom)' },
+                // Per-corner radius (rectangle and group layers)
+                cornerRadiusTopLeft: { type: 'number', description: 'Per-corner radius: top-left' },
+                cornerRadiusTopRight: { type: 'number', description: 'Per-corner radius: top-right' },
+                cornerRadiusBottomRight: { type: 'number', description: 'Per-corner radius: bottom-right' },
+                cornerRadiusBottomLeft: { type: 'number', description: 'Per-corner radius: bottom-left' },
             },
             required: ['layerId'],
         },
@@ -560,12 +1549,15 @@ IMPORTANT - Two effect pipelines:
                         'dither-floyd-steinberg', 'dither-atkinson', 'dither-jarvis-judice-ninke',
                         'dither-stucki', 'dither-burkes', 'dither-sierra', 'dither-two-row-sierra',
                         'dither-sierra-lite',
+                        'color-separation',
                         // Halftone (WebGPU - supports post-processes)
                         'halftone-mono', 'halftone-cmyk',
                         // Glitch (WebGPU - supports post-processes)
                         'glitch-chromatic', 'glitch-digital', 'glitch-vhs', 'glitch-weird',
                         // Art (WebGPU - supports post-processes)
                         'art-kuwahara', 'art-crosshatch', 'art-lineart', 'art-engraving', 'art-stipple',
+                        // Special (WebGPU - supports post-processes)
+                        'special-warp',
                     ],
                     description: 'Effect ID to apply',
                 },
@@ -611,7 +1603,7 @@ Common combinations:
                         'scanlines', 'vignette', 'chromatic-aberration', 'curvature',
                         'grain', 'noise', 'pixelate', 'wave', 'rgb-glitch', 'brightness-contrast',
                         'color-tint', 'palette', 'jitter', 'bloom', 'dot-screen', 'sepia',
-                        'grid', 'light-beams', 'motion-blur',
+                        'grid', 'light-beams', 'motion-blur', 'blob-tracking',
                     ],
                     description: 'Post-process type',
                 },
@@ -669,6 +1661,17 @@ Common combinations:
                 density: { type: 'number', description: 'Light-beams: ray spread (0.5-2)', default: 1 },
                 animated: { type: 'boolean', description: 'Light-beams/Grid: enable animation', default: false },
                 particleAmount: { type: 'number', description: 'Light-beams: particle density (0-1)', default: 0.5 },
+                // Blob Tracking
+                rectScale: { type: 'number', description: 'Blob-tracking: rectangle size multiplier (0.3-3)', default: 1 },
+                zoom: { type: 'number', description: 'Blob-tracking: zoom factor inside rectangles (0.2-1.0)', default: 0.6 },
+                invertChance: { type: 'number', description: 'Blob-tracking: chance of inverting colors (0-1)', default: 0.08 },
+                animSpeed: { type: 'number', description: 'Blob-tracking: animation speed (0-3)', default: 1 },
+                lineColor: { type: 'string', description: 'Blob-tracking: connecting line color (hex)', default: '#ffffff' },
+                lineOpacity: { type: 'number', description: 'Blob-tracking: line opacity (0-1)', default: 0.7 },
+                rectColor: { type: 'string', description: 'Blob-tracking: rectangle outline color (hex)', default: '#ffff00' },
+                rectOpacity: { type: 'number', description: 'Blob-tracking: rectangle opacity (0-1)', default: 1 },
+                showLabels: { type: 'boolean', description: 'Blob-tracking: show tracking ID labels', default: true },
+                glow: { type: 'number', description: 'Blob-tracking: glow intensity (0-1)', default: 0.3 },
             },
             required: ['type'],
         },
@@ -684,6 +1687,22 @@ Common combinations:
             required: ['layerId'],
         },
     },
+    {
+        name: 'move_layer',
+        description: 'Move a layer in the layer stack (z-order). Cannot move the background layer (index 0).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layerId: { type: 'string', description: 'ID of the layer to move' },
+                direction: {
+                    type: 'string',
+                    enum: ['up', 'down', 'top', 'bottom'],
+                    description: 'Where to move it: up/down = one step, top/bottom = to front/back',
+                },
+            },
+            required: ['layerId', 'direction'],
+        },
+    },
     {
         name: 'get_state',
         description: 'Get the current poster state as LayerShareState JSON (for debugging or verification)',
@@ -733,11 +1752,24 @@ async function handleStateTool(name, args) {
         case 'create_poster': {
             const aspectRatio = params.aspectRatio || '9:16';
             const backgroundColor = params.backgroundColor || '#1a1a1a';
+            const canvasColor = params.canvasColor;
+            const overflow = params.overflow;
             currentPoster = {
-                canvas: { aspectRatio, backgroundColor },
+                canvas: {
+                    aspectRatio,
+                    backgroundColor,
+                    ...(canvasColor && { canvasColor }),
+                    ...(overflow && { overflow }),
+                    layoutMode: 'column',
+                    alignItems: 'center',
+                    justifyContent: 'start',
+                    gap: 0.04,
+                    padding: { top: 0.08, right: 0.08, bottom: 0.08, left: 0.08 },
+                },
                 layers: [createDefaultBackgroundLayer(backgroundColor)],
                 postProcesses: [],
             };
+            persistState();
             return {
                 content: [
                     {
@@ -752,12 +1784,110 @@ async function handleStateTool(name, args) {
                 ],
             };
         }
-        case 'set_background': {
-            if (!currentPoster) {
-                return {
-                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
+        case 'clear_poster': {
+            ensurePoster();
+            const bgLayer = currentPoster.layers.find((l) => l.type === 'background');
+            const defaultBg = createDefaultBackgroundLayer(currentPoster.canvas.backgroundColor || '#1a1a1a');
+            currentPoster = {
+                canvas: { ...currentPoster.canvas },
+                layers: bgLayer ? [bgLayer] : [defaultBg],
+                postProcesses: [],
+            };
+            persistState();
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: 'Poster cleared — all content layers, effects, and post-processes removed.',
+                        }),
+                    }],
+            };
+        }
+        case 'set_page_layout': {
+            ensurePoster();
+            const layoutMode = params.layoutMode;
+            if (layoutMode !== undefined) {
+                if (layoutMode !== 'absolute' && layoutMode !== 'row' && layoutMode !== 'column') {
+                    return {
+                        content: [{ type: 'text', text: 'Error: layoutMode must be one of: absolute, row, column' }],
+                    };
+                }
+                currentPoster.canvas.layoutMode = layoutMode;
+            }
+            if (params.justifyContent !== undefined) {
+                currentPoster.canvas.justifyContent = params.justifyContent;
+            }
+            if (params.alignItems !== undefined) {
+                currentPoster.canvas.alignItems = params.alignItems;
+            }
+            if (params.wrap !== undefined) {
+                currentPoster.canvas.wrap = Boolean(params.wrap);
+            }
+            if (params.gap !== undefined) {
+                currentPoster.canvas.gap = cssPercentToSize(params.gap, (currentPoster.canvas.gap ?? 0) * 100);
+            }
+            if (params.padding !== undefined ||
+                params.paddingTop !== undefined ||
+                params.paddingRight !== undefined ||
+                params.paddingBottom !== undefined ||
+                params.paddingLeft !== undefined) {
+                const existing = currentPoster.canvas.padding || { top: 0, right: 0, bottom: 0, left: 0 };
+                const uniformPct = params.padding !== undefined ? parseNumericInput(params.padding) : undefined;
+                const uniform = uniformPct !== undefined ? cssPercentToSize(uniformPct, 0) : undefined;
+                const nextPadding = {
+                    top: params.paddingTop !== undefined ? cssPercentToSize(params.paddingTop, 0) : uniform ?? existing.top,
+                    right: params.paddingRight !== undefined ? cssPercentToSize(params.paddingRight, 0) : uniform ?? existing.right,
+                    bottom: params.paddingBottom !== undefined ? cssPercentToSize(params.paddingBottom, 0) : uniform ?? existing.bottom,
+                    left: params.paddingLeft !== undefined ? cssPercentToSize(params.paddingLeft, 0) : uniform ?? existing.left,
                 };
+                currentPoster.canvas.padding = nextPadding;
             }
+            persistState();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Page layout updated (${currentPoster.canvas.layoutMode ?? 'absolute'})`,
+                            canvas: currentPoster.canvas,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        case 'modify_canvas': {
+            ensurePoster();
+            const canvas = currentPoster.canvas;
+            if (params.aspectRatio)
+                canvas.aspectRatio = params.aspectRatio;
+            if (params.backgroundColor)
+                canvas.backgroundColor = params.backgroundColor;
+            if (params.canvasColor !== undefined)
+                canvas.canvasColor = params.canvasColor;
+            if (params.overflow !== undefined)
+                canvas.overflow = params.overflow;
+            persistState();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            canvas: {
+                                aspectRatio: canvas.aspectRatio,
+                                backgroundColor: canvas.backgroundColor,
+                                canvasColor: canvas.canvasColor,
+                                overflow: canvas.overflow,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        case 'set_background': {
+            ensurePoster();
             // Background is always at index 0
             const bgLayer = currentPoster.layers[0];
             if (bgLayer.type !== 'background') {
@@ -765,13 +1895,34 @@ 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 gradient = buildFillFromParams(params)
+                    ?? normalizeLinearGradientFill(DEFAULT_LINEAR_GRADIENT_FILL);
+                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) {
@@ -794,6 +1945,7 @@ async function handleStateTool(name, args) {
                     objectFit: params.objectFit || 'cover',
                 };
             }
+            persistState();
             return {
                 content: [
                     {
@@ -808,11 +1960,7 @@ async function handleStateTool(name, args) {
             };
         }
         case 'add_layer': {
-            if (!currentPoster) {
-                return {
-                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
-                };
-            }
+            ensurePoster();
             const layerType = params.type;
             if (!layerType) {
                 return {
@@ -824,38 +1972,76 @@ async function handleStateTool(name, args) {
                     content: [{ type: 'text', text: 'Error: Use set_background to modify the background layer' }],
                 };
             }
+            const isShapeType = ['rectangle', 'ellipse', 'polygon', 'star', 'line'].includes(layerType);
             const layerId = generateId();
+            const visualOverrides = parseVisualOverrides(params);
+            const originOverrides = parseTransformOrigin(params);
             const baseLayer = {
                 id: layerId,
                 type: layerType,
                 name: params.name || `${layerType.charAt(0).toUpperCase() + layerType.slice(1)} Layer`,
                 visible: true,
                 locked: false,
+                ...parseFlexChildProps(params),
+                ...visualOverrides,
                 transform: {
-                    x: params.x ?? 0,
-                    y: params.y ?? 0,
-                    width: params.width ?? 1,
-                    height: params.height ?? 1,
+                    x: cssPercentToX(params.x, 50),
+                    y: cssPercentToY(params.y, 50),
+                    // Shapes store their intrinsic size in geometry fields; keep transform scale at 1.
+                    width: isShapeType ? 1 : cssPercentToSize(params.width, 100),
+                    height: isShapeType ? 1 : cssPercentToSize(params.height, 100),
                     rotation: params.rotation ?? 0,
-                    opacity: params.opacity ?? 1,
+                    opacity: normalizeOpacity(params.opacity, 1),
+                    ...originOverrides,
                 },
             };
             let layer;
             if (layerType === 'text') {
                 const animation = buildAnimationSettings(params);
-                // Use same defaults as app's DEFAULT_TEXT_LAYER to avoid encoding unnecessary params in URLs
+                const artboardAspect = getArtboardAspect(currentPoster.canvas.aspectRatio);
+                const content = params.content || 'Text';
+                const fontSize = params.fontSize || 72;
+                const frameWidthNormalized = parseNormalizedFrameDimension(params.frameWidth);
+                const frameHeightNormalized = parseNormalizedFrameDimension(params.frameHeight);
+                const frameWidthPxFromNormalized = frameWidthNormalized !== undefined
+                    ? textNormalizedToPx(frameWidthNormalized, artboardAspect, 'width')
+                    : undefined;
+                const frameHeightPxFromNormalized = frameHeightNormalized !== undefined
+                    ? textNormalizedToPx(frameHeightNormalized, artboardAspect, 'height')
+                    : undefined;
+                // All text is frame text — silently convert any 'point'/'scale' requests
+                let frameWidthPx = typeof params.frameWidthPx === 'number' ? params.frameWidthPx : frameWidthPxFromNormalized;
+                const frameHeightPx = typeof params.frameHeightPx === 'number' ? params.frameHeightPx : frameHeightPxFromNormalized;
+                const textBoxWidth = typeof params.textBoxWidth === 'number' ? params.textBoxWidth : undefined;
+                const requestedAutoSize = typeof params.autoSize === 'string'
+                    ? params.autoSize
+                    : undefined;
+                const autoSize = requestedAutoSize ?? 'height';
+                if (frameWidthPx == null && textBoxWidth == null) {
+                    const defaultFrameWidthNormalized = fontSize >= 72 ? 0.88 : 0.78;
+                    frameWidthPx = textNormalizedToPx(defaultFrameWidthNormalized, artboardAspect, 'width');
+                }
                 layer = {
                     ...baseLayer,
                     type: 'text',
-                    content: params.content || 'Text',
+                    content,
+                    textType: 'frame',
                     fontFamily: normalizeFontFamily(params.fontFamily),
-                    fontSize: params.fontSize || 72,
+                    fontSize,
                     fontWeight: normalizeFontWeight(params.fontWeight),
                     color: params.color || '#ffffff',
                     textAlign: params.textAlign || 'center',
+                    ...(params.verticalAlign ? { verticalAlign: params.verticalAlign } : {}),
                     letterSpacing: params.letterSpacing ?? 0,
                     lineHeight: params.lineHeight ?? 1.2,
-                    ...(animation && { animation }),
+                    textTransformMode: 'box',
+                    ...(typeof textBoxWidth === 'number' ? { textBoxWidth } : {}),
+                    ...(typeof frameWidthPx === 'number' ? { frameWidthPx } : {}),
+                    ...(typeof frameHeightPx === 'number' ? { frameHeightPx } : {}),
+                    ...(typeof autoSize === 'string' ? { autoSize } : {}),
+                    ...(animation ? { animation } : {}),
+                    ...(parseTextTransform(params) ? { textTransform: parseTextTransform(params) } : {}),
+                    ...parseTextDecoration(params),
                 };
             }
             else if (layerType === 'image') {
@@ -892,10 +2078,140 @@ async function handleStateTool(name, args) {
                     playbackSpeed: 1,
                 };
             }
+            else if (layerType === 'rectangle') {
+                const fillColor = normalizeHexColor(params.fillColor) || '#3b82f6';
+                const fillOpacity = normalizeOpacity(params.fillOpacity, 1);
+                const strokeColor = normalizeHexColor(params.strokeColor) || '#000000';
+                const gradientFill = buildFillFromParams(params);
+                layer = {
+                    ...baseLayer,
+                    type: 'rectangle',
+                    style: {
+                        fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                        fillType: 'solid',
+                        fillColor,
+                        fillOpacity,
+                        strokeColor,
+                        strokeWidth: normalizeStrokeWidth(params.strokeWidth, 0),
+                        strokeOpacity: normalizeOpacity(params.strokeOpacity, 1),
+                        strokeCap: 'round',
+                        strokeJoin: 'round',
+                    },
+                    shapeWidth: cssPercentToSize(params.width, 20),
+                    shapeHeight: cssPercentToSize(params.height, 20),
+                    cornerRadius: normalizeCornerRadius(params.cornerRadius, 0),
+                    ...(parseCornerRadii(params) ? { cornerRadii: parseCornerRadii(params) } : {}),
+                };
+            }
+            else if (layerType === 'ellipse') {
+                const fillColor = normalizeHexColor(params.fillColor) || '#3b82f6';
+                const fillOpacity = normalizeOpacity(params.fillOpacity, 1);
+                const strokeColor = normalizeHexColor(params.strokeColor) || '#000000';
+                const w = cssPercentToSize(params.width, 20);
+                const h = cssPercentToSize(params.height, 20);
+                const gradientFill = buildFillFromParams(params);
+                layer = {
+                    ...baseLayer,
+                    type: 'ellipse',
+                    style: {
+                        fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                        fillType: 'solid',
+                        fillColor,
+                        fillOpacity,
+                        strokeColor,
+                        strokeWidth: normalizeStrokeWidth(params.strokeWidth, 0),
+                        strokeOpacity: normalizeOpacity(params.strokeOpacity, 1),
+                        strokeCap: 'round',
+                        strokeJoin: 'round',
+                    },
+                    radiusX: w / 2,
+                    radiusY: h / 2,
+                };
+            }
+            else if (layerType === 'polygon') {
+                const fillColor = normalizeHexColor(params.fillColor) || '#3b82f6';
+                const fillOpacity = normalizeOpacity(params.fillOpacity, 1);
+                const strokeColor = normalizeHexColor(params.strokeColor) || '#000000';
+                const w = cssPercentToSize(params.width, 20);
+                const h = cssPercentToSize(params.height, 20);
+                const gradientFill = buildFillFromParams(params);
+                layer = {
+                    ...baseLayer,
+                    type: 'polygon',
+                    style: {
+                        fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                        fillType: 'solid',
+                        fillColor,
+                        fillOpacity,
+                        strokeColor,
+                        strokeWidth: normalizeStrokeWidth(params.strokeWidth, 0),
+                        strokeOpacity: normalizeOpacity(params.strokeOpacity, 1),
+                        strokeCap: 'round',
+                        strokeJoin: 'round',
+                    },
+                    radius: Math.min(w, h) / 2,
+                    sides: normalizePositiveInt(params.sides, 6, 3, 32),
+                    cornerRadius: normalizeCornerRadius(params.cornerRadius, 0),
+                };
+            }
+            else if (layerType === 'star') {
+                const fillColor = normalizeHexColor(params.fillColor) || '#3b82f6';
+                const fillOpacity = normalizeOpacity(params.fillOpacity, 1);
+                const strokeColor = normalizeHexColor(params.strokeColor) || '#000000';
+                const w = cssPercentToSize(params.width, 20);
+                const h = cssPercentToSize(params.height, 20);
+                const gradientFill = buildFillFromParams(params);
+                layer = {
+                    ...baseLayer,
+                    type: 'star',
+                    style: {
+                        fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                        fillType: 'solid',
+                        fillColor,
+                        fillOpacity,
+                        strokeColor,
+                        strokeWidth: normalizeStrokeWidth(params.strokeWidth, 0),
+                        strokeOpacity: normalizeOpacity(params.strokeOpacity, 1),
+                        strokeCap: 'round',
+                        strokeJoin: 'round',
+                    },
+                    outerRadius: Math.min(w, h) / 2,
+                    innerRadiusRatio: clamp(parseNumericInput(params.innerRadiusRatio), 0.05, 0.95, 0.5),
+                    points: normalizePositiveInt(params.points, 5, 3, 32),
+                    cornerRadius: normalizeCornerRadius(params.cornerRadius, 0),
+                };
+            }
+            else if (layerType === 'line') {
+                const strokeColor = normalizeHexColor(params.strokeColor) || '#000000';
+                const strokeWidth = normalizeStrokeWidth(params.strokeWidth, 0.005);
+                const strokeOpacity = normalizeOpacity(params.strokeOpacity, 1);
+                const halfW = clamp(parseNumericInput(params.width), 0.01, 1, 0.6);
+                const halfH = clamp(parseNumericInput(params.height), 0, 1, 0);
+                const startX = cssPercentToX(params.startX, (-halfW + 1) * 50);
+                const endX = cssPercentToX(params.endX, (halfW + 1) * 50);
+                const startY = cssPercentToY(params.startY, (1 + halfH) * 50);
+                const endY = cssPercentToY(params.endY, (1 - halfH) * 50);
+                layer = {
+                    ...baseLayer,
+                    type: 'line',
+                    style: {
+                        strokeColor,
+                        strokeWidth,
+                        strokeOpacity,
+                        strokeCap: 'round',
+                        strokeJoin: 'round',
+                    },
+                    startX,
+                    startY,
+                    endX,
+                    endY,
+                };
+            }
             else {
                 layer = baseLayer;
             }
             currentPoster.layers.push(layer);
+            persistState();
             return {
                 content: [
                     {
@@ -910,12 +2226,308 @@ async function handleStateTool(name, args) {
                 ],
             };
         }
-        case 'modify_layer': {
-            if (!currentPoster) {
+        case 'add_group': {
+            ensurePoster();
+            const children = params.children;
+            if (!children || !Array.isArray(children) || children.length === 0) {
                 return {
-                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
+                    content: [{ type: 'text', text: 'Error: children array is required and must have at least 1 child' }],
                 };
             }
+            const groupId = generateId();
+            const childLayers = [];
+            const artboardAspect = getArtboardAspect(currentPoster.canvas.aspectRatio);
+            for (const childParams of children) {
+                const childType = childParams.type || 'text';
+                const isChildShapeType = ['rectangle', 'ellipse', 'polygon', 'star', 'line'].includes(childType);
+                const childId = generateId();
+                const childVisualOverrides = parseVisualOverrides(childParams);
+                const childOriginOverrides = parseTransformOrigin(childParams);
+                const childBase = {
+                    id: childId,
+                    type: childType,
+                    name: childParams.name || `${childType.charAt(0).toUpperCase() + childType.slice(1)} Layer`,
+                    visible: true,
+                    locked: false,
+                    ...parseFlexChildProps(childParams),
+                    ...childVisualOverrides,
+                    transform: {
+                        x: 0,
+                        y: 0,
+                        // Shapes store intrinsic size in geometry fields; keep transform scale at 1.
+                        width: isChildShapeType ? 1 : cssPercentToSize(childParams.width, 100),
+                        height: isChildShapeType ? 1 : cssPercentToSize(childParams.height, 100),
+                        rotation: 0,
+                        opacity: normalizeOpacity(childParams.opacity, 1),
+                        ...childOriginOverrides,
+                    },
+                };
+                if (childType === 'text') {
+                    const frameWidthNormalized = parseNormalizedFrameDimension(childParams.frameWidth);
+                    const frameHeightNormalized = parseNormalizedFrameDimension(childParams.frameHeight);
+                    const frameWidthPxFromNormalized = frameWidthNormalized !== undefined
+                        ? textNormalizedToPx(frameWidthNormalized, artboardAspect, 'width')
+                        : undefined;
+                    const frameHeightPxFromNormalized = frameHeightNormalized !== undefined
+                        ? textNormalizedToPx(frameHeightNormalized, artboardAspect, 'height')
+                        : undefined;
+                    // All text is frame text
+                    let frameWidthPx = typeof childParams.frameWidthPx === 'number' ? childParams.frameWidthPx : frameWidthPxFromNormalized;
+                    const frameHeightPx = typeof childParams.frameHeightPx === 'number' ? childParams.frameHeightPx : frameHeightPxFromNormalized;
+                    const textBoxWidth = typeof childParams.textBoxWidth === 'number' ? childParams.textBoxWidth : undefined;
+                    const childFontSize = childParams.fontSize || 72;
+                    // Default frameWidthPx for group text children (same as add_layer)
+                    if (frameWidthPx == null && textBoxWidth == null) {
+                        const defaultFrameWidthNormalized = childFontSize >= 72 ? 0.88 : 0.78;
+                        frameWidthPx = textNormalizedToPx(defaultFrameWidthNormalized, artboardAspect, 'width');
+                    }
+                    childLayers.push({
+                        ...childBase,
+                        type: 'text',
+                        content: childParams.content || 'Text',
+                        textType: 'frame',
+                        fontFamily: normalizeFontFamily(childParams.fontFamily),
+                        fontSize: childFontSize,
+                        fontWeight: normalizeFontWeight(childParams.fontWeight),
+                        color: childParams.color || '#ffffff',
+                        textAlign: childParams.textAlign || 'center',
+                        ...(childParams.verticalAlign ? { verticalAlign: childParams.verticalAlign } : {}),
+                        letterSpacing: childParams.letterSpacing ?? 0,
+                        lineHeight: childParams.lineHeight ?? 1.2,
+                        textTransformMode: 'box',
+                        ...(textBoxWidth != null ? { textBoxWidth } : {}),
+                        frameWidthPx,
+                        ...(typeof frameHeightPx === 'number' ? { frameHeightPx } : {}),
+                        ...(childParams.autoSize ? { autoSize: childParams.autoSize } : { autoSize: 'height' }),
+                        ...(parseTextTransform(childParams) ? { textTransform: parseTextTransform(childParams) } : {}),
+                        ...parseTextDecoration(childParams),
+                    });
+                }
+                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,
+                    });
+                }
+                else if (childType === 'rectangle') {
+                    const fillColor = normalizeHexColor(childParams.fillColor) || '#3b82f6';
+                    const fillOpacity = normalizeOpacity(childParams.fillOpacity, 1);
+                    const strokeColor = normalizeHexColor(childParams.strokeColor) || '#000000';
+                    const gradientFill = buildFillFromParams(childParams);
+                    childLayers.push({
+                        ...childBase,
+                        type: 'rectangle',
+                        style: {
+                            fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                            fillType: 'solid',
+                            fillColor,
+                            fillOpacity,
+                            strokeColor,
+                            strokeWidth: normalizeStrokeWidth(childParams.strokeWidth, 0),
+                            strokeOpacity: normalizeOpacity(childParams.strokeOpacity, 1),
+                            strokeCap: 'round',
+                            strokeJoin: 'round',
+                        },
+                        shapeWidth: cssPercentToSize(childParams.width, 20),
+                        shapeHeight: cssPercentToSize(childParams.height, 20),
+                        cornerRadius: normalizeCornerRadius(childParams.cornerRadius, 0),
+                        ...(parseCornerRadii(childParams) ? { cornerRadii: parseCornerRadii(childParams) } : {}),
+                    });
+                }
+                else if (childType === 'ellipse') {
+                    const fillColor = normalizeHexColor(childParams.fillColor) || '#3b82f6';
+                    const fillOpacity = normalizeOpacity(childParams.fillOpacity, 1);
+                    const strokeColor = normalizeHexColor(childParams.strokeColor) || '#000000';
+                    const w = cssPercentToSize(childParams.width, 20);
+                    const h = cssPercentToSize(childParams.height, 20);
+                    const gradientFill = buildFillFromParams(childParams);
+                    childLayers.push({
+                        ...childBase,
+                        type: 'ellipse',
+                        style: {
+                            fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                            fillType: 'solid',
+                            fillColor,
+                            fillOpacity,
+                            strokeColor,
+                            strokeWidth: normalizeStrokeWidth(childParams.strokeWidth, 0),
+                            strokeOpacity: normalizeOpacity(childParams.strokeOpacity, 1),
+                            strokeCap: 'round',
+                            strokeJoin: 'round',
+                        },
+                        radiusX: w / 2,
+                        radiusY: h / 2,
+                    });
+                }
+                else if (childType === 'polygon') {
+                    const fillColor = normalizeHexColor(childParams.fillColor) || '#3b82f6';
+                    const fillOpacity = normalizeOpacity(childParams.fillOpacity, 1);
+                    const strokeColor = normalizeHexColor(childParams.strokeColor) || '#000000';
+                    const w = cssPercentToSize(childParams.width, 20);
+                    const h = cssPercentToSize(childParams.height, 20);
+                    const gradientFill = buildFillFromParams(childParams);
+                    childLayers.push({
+                        ...childBase,
+                        type: 'polygon',
+                        style: {
+                            fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                            fillType: 'solid',
+                            fillColor,
+                            fillOpacity,
+                            strokeColor,
+                            strokeWidth: normalizeStrokeWidth(childParams.strokeWidth, 0),
+                            strokeOpacity: normalizeOpacity(childParams.strokeOpacity, 1),
+                            strokeCap: 'round',
+                            strokeJoin: 'round',
+                        },
+                        radius: Math.min(w, h) / 2,
+                        sides: normalizePositiveInt(childParams.sides, 6, 3, 32),
+                        cornerRadius: normalizeCornerRadius(childParams.cornerRadius, 0),
+                    });
+                }
+                else if (childType === 'star') {
+                    const fillColor = normalizeHexColor(childParams.fillColor) || '#3b82f6';
+                    const fillOpacity = normalizeOpacity(childParams.fillOpacity, 1);
+                    const strokeColor = normalizeHexColor(childParams.strokeColor) || '#000000';
+                    const w = cssPercentToSize(childParams.width, 20);
+                    const h = cssPercentToSize(childParams.height, 20);
+                    const gradientFill = buildFillFromParams(childParams);
+                    childLayers.push({
+                        ...childBase,
+                        type: 'star',
+                        style: {
+                            fill: gradientFill ?? { type: 'solid', color: fillColor, opacity: fillOpacity },
+                            fillType: 'solid',
+                            fillColor,
+                            fillOpacity,
+                            strokeColor,
+                            strokeWidth: normalizeStrokeWidth(childParams.strokeWidth, 0),
+                            strokeOpacity: normalizeOpacity(childParams.strokeOpacity, 1),
+                            strokeCap: 'round',
+                            strokeJoin: 'round',
+                        },
+                        outerRadius: Math.min(w, h) / 2,
+                        innerRadiusRatio: clamp(parseNumericInput(childParams.innerRadiusRatio), 0.05, 0.95, 0.5),
+                        points: normalizePositiveInt(childParams.points, 5, 3, 32),
+                        cornerRadius: normalizeCornerRadius(childParams.cornerRadius, 0),
+                    });
+                }
+                else if (childType === 'line') {
+                    const strokeColor = normalizeHexColor(childParams.strokeColor) || '#000000';
+                    const strokeWidth = normalizeStrokeWidth(childParams.strokeWidth, 0.005);
+                    const strokeOpacity = normalizeOpacity(childParams.strokeOpacity, 1);
+                    const halfW = clamp(parseNumericInput(childParams.width), 0.01, 1, 0.6);
+                    const halfH = clamp(parseNumericInput(childParams.height), 0, 1, 0);
+                    const startX = cssPercentToX(childParams.startX, (-halfW + 1) * 50);
+                    const endX = cssPercentToX(childParams.endX, (halfW + 1) * 50);
+                    const startY = cssPercentToY(childParams.startY, (1 + halfH) * 50);
+                    const endY = cssPercentToY(childParams.endY, (1 - halfH) * 50);
+                    childLayers.push({
+                        ...childBase,
+                        type: 'line',
+                        style: {
+                            strokeColor,
+                            strokeWidth,
+                            strokeOpacity,
+                            strokeCap: 'round',
+                            strokeJoin: 'round',
+                        },
+                        startX,
+                        startY,
+                        endX,
+                        endY,
+                    });
+                }
+            }
+            if (childLayers.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: No valid child layers could be created' }],
+                };
+            }
+            // Build padding — convert from CSS % to internal normalized values
+            const uniformPaddingPct = params.padding ?? 0;
+            const uniformPadding = cssPercentToSize(uniformPaddingPct, 0);
+            const groupPadding = {
+                top: cssPercentToSize(params.paddingTop ?? uniformPaddingPct, 0),
+                right: cssPercentToSize(params.paddingRight ?? uniformPaddingPct, 0),
+                bottom: cssPercentToSize(params.paddingBottom ?? uniformPaddingPct, 0),
+                left: cssPercentToSize(params.paddingLeft ?? uniformPaddingPct, 0),
+            };
+            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 = cssPercentToSize(params.width, 60);
+            const baseHeight = cssPercentToSize(params.height, 40);
+            const groupLayer = {
+                id: groupId,
+                type: 'group',
+                name: params.name || 'Group',
+                visible: true,
+                locked: false,
+                transform: {
+                    x: cssPercentToX(params.x, 50),
+                    y: cssPercentToY(params.y, 50),
+                    width: 1,
+                    height: 1,
+                    rotation: params.rotation ?? 0,
+                    opacity: normalizeOpacity(params.opacity, 1),
+                },
+                children: childLayers,
+                expanded: true,
+                baseWidth,
+                baseHeight,
+                layoutMode,
+                widthMode,
+                heightMode,
+                gap: cssPercentToSize(params.gap, 2),
+                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);
+            persistState();
+            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': {
+            ensurePoster();
             const layerId = params.layerId;
             if (!layerId) {
                 return {
@@ -929,11 +2541,28 @@ async function handleStateTool(name, args) {
                 };
             }
             const layer = currentPoster.layers[layerIndex];
+            const isShapeType = ['rectangle', 'ellipse', 'polygon', 'star', 'line'].includes(layer.type);
             // Update transform properties
-            const transformKeys = ['x', 'y', 'width', 'height', 'rotation', 'opacity'];
+            const transformKeys = isShapeType
+                ? ['x', 'y', 'rotation', 'opacity']
+                : ['x', 'y', 'width', 'height', 'rotation', 'opacity'];
             for (const key of transformKeys) {
                 if (params[key] !== undefined) {
-                    layer.transform[key] = params[key];
+                    if (key === 'x') {
+                        layer.transform[key] = cssPercentToX(params[key], (layer.transform[key] + 1) * 50);
+                    }
+                    else if (key === 'y') {
+                        layer.transform[key] = cssPercentToY(params[key], (1 - layer.transform[key]) * 50);
+                    }
+                    else if (key === 'opacity') {
+                        layer.transform[key] = normalizeOpacity(params[key], layer.transform[key]);
+                    }
+                    else if (key === 'width' || key === 'height') {
+                        layer.transform[key] = cssPercentToSize(params[key], layer.transform[key] * 100);
+                    }
+                    else {
+                        layer.transform[key] = params[key];
+                    }
                 }
             }
             // Update base properties
@@ -943,9 +2572,46 @@ async function handleStateTool(name, args) {
                 layer.locked = params.locked;
             if (params.name !== undefined)
                 layer.name = params.name;
+            // Update flex-child properties
+            const flexProps = parseFlexChildProps(params);
+            if (flexProps.positioning !== undefined)
+                layer.positioning = flexProps.positioning;
+            if (flexProps.flexWidthMode !== undefined)
+                layer.flexWidthMode = flexProps.flexWidthMode;
+            if (flexProps.flexHeightMode !== undefined)
+                layer.flexHeightMode = flexProps.flexHeightMode;
+            if (flexProps.alignSelf !== undefined)
+                layer.alignSelf = flexProps.alignSelf;
+            if (flexProps.flexGrow !== undefined)
+                layer.flexGrow = flexProps.flexGrow;
+            // Update visual props (shadow, blendMode, margin, min/max, transform origin — all layer types)
+            const shadow = parseShadowParams(params);
+            if (shadow)
+                layer.shadow = shadow;
+            const blendMode = parseBlendMode(params);
+            if (blendMode !== undefined)
+                layer.blendMode = blendMode;
+            const margin = parseMarginParams(params);
+            if (margin)
+                layer.margin = margin;
+            const constraints = parseMinMaxConstraints(params);
+            if (constraints.minWidth !== undefined)
+                layer.minWidth = constraints.minWidth;
+            if (constraints.maxWidth !== undefined)
+                layer.maxWidth = constraints.maxWidth;
+            if (constraints.minHeight !== undefined)
+                layer.minHeight = constraints.minHeight;
+            if (constraints.maxHeight !== undefined)
+                layer.maxHeight = constraints.maxHeight;
+            const originOverrides = parseTransformOrigin(params);
+            if (originOverrides.originX !== undefined)
+                layer.transform.originX = originOverrides.originX;
+            if (originOverrides.originY !== undefined)
+                layer.transform.originY = originOverrides.originY;
             // Update text layer properties
             if (layer.type === 'text') {
                 const textLayer = layer;
+                const artboardAspect = getArtboardAspect(currentPoster.canvas.aspectRatio);
                 if (params.content !== undefined)
                     textLayer.content = params.content;
                 if (params.fontFamily !== undefined)
@@ -958,10 +2624,46 @@ async function handleStateTool(name, args) {
                     textLayer.color = params.color;
                 if (params.textAlign !== undefined)
                     textLayer.textAlign = params.textAlign;
+                if (params.verticalAlign !== undefined)
+                    textLayer.verticalAlign = params.verticalAlign;
                 if (params.letterSpacing !== undefined)
                     textLayer.letterSpacing = params.letterSpacing;
                 if (params.lineHeight !== undefined)
                     textLayer.lineHeight = params.lineHeight;
+                // All text is frame text — silently ignore any 'point'/'scale' requests
+                textLayer.textType = 'frame';
+                textLayer.textTransformMode = '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;
+                // Text CSS properties
+                const tt = parseTextTransform(params);
+                if (tt !== undefined)
+                    textLayer.textTransform = tt;
+                else if (params.textTransform === 'none')
+                    textLayer.textTransform = undefined;
+                const td = parseTextDecoration(params);
+                if (td.textDecoration !== undefined)
+                    textLayer.textDecoration = td.textDecoration;
+                else if (params.textDecoration === 'none')
+                    textLayer.textDecoration = undefined;
+                if (td.textDecorationColor !== undefined)
+                    textLayer.textDecorationColor = td.textDecorationColor;
+                if (td.textDecorationThickness !== undefined)
+                    textLayer.textDecorationThickness = td.textDecorationThickness;
+                const frameWidthNormalized = parseNormalizedFrameDimension(params.frameWidth);
+                if (frameWidthNormalized !== undefined && params.frameWidthPx === undefined) {
+                    textLayer.frameWidthPx = textNormalizedToPx(frameWidthNormalized, artboardAspect, 'width');
+                }
+                const frameHeightNormalized = parseNormalizedFrameDimension(params.frameHeight);
+                if (frameHeightNormalized !== undefined && params.frameHeightPx === undefined) {
+                    textLayer.frameHeightPx = textNormalizedToPx(frameHeightNormalized, artboardAspect, 'height');
+                }
                 // Update animation settings
                 if (params.animationType !== undefined) {
                     if (params.animationType === 'none') {
@@ -1095,6 +2797,177 @@ 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 = cssPercentToSize(params.gap, (groupLayer.gap ?? 0.02) * 100);
+                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;
+                const groupCornerRadii = parseCornerRadii(params);
+                if (groupCornerRadii)
+                    groupLayer.cornerRadii = groupCornerRadii;
+                // Padding: uniform or individual overrides (CSS % to normalized)
+                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 uniformPct = params.padding !== undefined ? parseNumericInput(params.padding) : undefined;
+                    const uniform = uniformPct !== undefined ? cssPercentToSize(uniformPct, 0) : undefined;
+                    groupLayer.padding = {
+                        top: params.paddingTop !== undefined ? cssPercentToSize(params.paddingTop, 0) : uniform ?? existing.top,
+                        right: params.paddingRight !== undefined ? cssPercentToSize(params.paddingRight, 0) : uniform ?? existing.right,
+                        bottom: params.paddingBottom !== undefined ? cssPercentToSize(params.paddingBottom, 0) : uniform ?? existing.bottom,
+                        left: params.paddingLeft !== undefined ? cssPercentToSize(params.paddingLeft, 0) : uniform ?? existing.left,
+                    };
+                }
+                // Allow updating baseWidth/baseHeight via width/height params
+                if (params.width !== undefined) {
+                    groupLayer.baseWidth = cssPercentToSize(params.width, groupLayer.baseWidth * 100);
+                    if (params.widthMode === undefined) {
+                        groupLayer.widthMode = 'fixed';
+                    }
+                }
+                if (params.height !== undefined) {
+                    groupLayer.baseHeight = cssPercentToSize(params.height, groupLayer.baseHeight * 100);
+                    if (params.heightMode === undefined) {
+                        groupLayer.heightMode = 'fixed';
+                    }
+                }
+            }
+            // Update shape properties (geometry + style)
+            if (isShapeType) {
+                const anyLayer = layer;
+                // Style (common)
+                if (!anyLayer.style)
+                    anyLayer.style = {};
+                if (params.fillColor !== undefined) {
+                    const existing = typeof anyLayer.style.fillColor === 'string' ? anyLayer.style.fillColor : '#3b82f6';
+                    anyLayer.style.fillColor = normalizeHexColor(params.fillColor) || existing;
+                }
+                if (params.fillOpacity !== undefined) {
+                    const existing = asFiniteNumber(anyLayer.style.fillOpacity, 1);
+                    anyLayer.style.fillOpacity = normalizeOpacity(params.fillOpacity, existing);
+                }
+                if (params.strokeColor !== undefined) {
+                    const existing = typeof anyLayer.style.strokeColor === 'string' ? anyLayer.style.strokeColor : '#000000';
+                    anyLayer.style.strokeColor = normalizeHexColor(params.strokeColor) || existing;
+                }
+                if (params.strokeWidth !== undefined) {
+                    const existing = asFiniteNumber(anyLayer.style.strokeWidth, 0);
+                    anyLayer.style.strokeWidth = normalizeStrokeWidth(params.strokeWidth, existing);
+                }
+                if (params.strokeOpacity !== undefined) {
+                    const existing = asFiniteNumber(anyLayer.style.strokeOpacity, 1);
+                    anyLayer.style.strokeOpacity = normalizeOpacity(params.strokeOpacity, existing);
+                }
+                // Gradient fill update
+                const modifyGradientFill = buildFillFromParams(params);
+                if (modifyGradientFill) {
+                    anyLayer.style.fill = modifyGradientFill;
+                    anyLayer.style.fillType = 'solid';
+                }
+                else if (params.fillColor !== undefined || params.fillOpacity !== undefined) {
+                    // Sync style.fill as solid when only color/opacity changed
+                    const currentFillColor = typeof anyLayer.style.fillColor === 'string' ? anyLayer.style.fillColor : '#3b82f6';
+                    const currentFillOpacity = asFiniteNumber(anyLayer.style.fillOpacity, 1);
+                    anyLayer.style.fill = { type: 'solid', color: currentFillColor, opacity: currentFillOpacity };
+                    anyLayer.style.fillType = 'solid';
+                }
+                if (anyLayer.style.fillType === undefined && layer.type !== 'line')
+                    anyLayer.style.fillType = 'solid';
+                if (anyLayer.style.strokeCap === undefined)
+                    anyLayer.style.strokeCap = 'round';
+                if (anyLayer.style.strokeJoin === undefined)
+                    anyLayer.style.strokeJoin = 'round';
+                if (layer.type === 'rectangle') {
+                    if (params.width !== undefined)
+                        anyLayer.shapeWidth = cssPercentToSize(params.width, asFiniteNumber(anyLayer.shapeWidth, 0.2) * 100);
+                    if (params.height !== undefined)
+                        anyLayer.shapeHeight = cssPercentToSize(params.height, asFiniteNumber(anyLayer.shapeHeight, 0.2) * 100);
+                    if (params.cornerRadius !== undefined)
+                        anyLayer.cornerRadius = normalizeCornerRadius(params.cornerRadius, asFiniteNumber(anyLayer.cornerRadius, 0));
+                    const rectCornerRadii = parseCornerRadii(params);
+                    if (rectCornerRadii)
+                        anyLayer.cornerRadii = rectCornerRadii;
+                }
+                else if (layer.type === 'ellipse') {
+                    if (params.width !== undefined)
+                        anyLayer.radiusX = cssPercentToSize(params.width, asFiniteNumber(anyLayer.radiusX, 0.1) * 2 * 100) / 2;
+                    if (params.height !== undefined)
+                        anyLayer.radiusY = cssPercentToSize(params.height, asFiniteNumber(anyLayer.radiusY, 0.1) * 2 * 100) / 2;
+                }
+                else if (layer.type === 'polygon') {
+                    if (params.width !== undefined || params.height !== undefined) {
+                        const baseRadius = asFiniteNumber(anyLayer.radius, 0.1);
+                        const w = params.width !== undefined ? cssPercentToSize(params.width, baseRadius * 2 * 100) : undefined;
+                        const h = params.height !== undefined ? cssPercentToSize(params.height, baseRadius * 2 * 100) : undefined;
+                        const size = Math.min(w ?? baseRadius * 2, h ?? baseRadius * 2);
+                        anyLayer.radius = size / 2;
+                    }
+                    if (params.sides !== undefined)
+                        anyLayer.sides = normalizePositiveInt(params.sides, asFiniteNumber(anyLayer.sides, 6), 3, 64);
+                    if (params.cornerRadius !== undefined)
+                        anyLayer.cornerRadius = normalizeCornerRadius(params.cornerRadius, asFiniteNumber(anyLayer.cornerRadius, 0));
+                }
+                else if (layer.type === 'star') {
+                    if (params.width !== undefined || params.height !== undefined) {
+                        const baseOuter = asFiniteNumber(anyLayer.outerRadius, 0.1);
+                        const w = params.width !== undefined ? cssPercentToSize(params.width, baseOuter * 2 * 100) : undefined;
+                        const h = params.height !== undefined ? cssPercentToSize(params.height, baseOuter * 2 * 100) : undefined;
+                        const size = Math.min(w ?? baseOuter * 2, h ?? baseOuter * 2);
+                        anyLayer.outerRadius = size / 2;
+                    }
+                    if (params.innerRadiusRatio !== undefined) {
+                        anyLayer.innerRadiusRatio = clamp(parseNumericInput(params.innerRadiusRatio), 0.05, 0.95, asFiniteNumber(anyLayer.innerRadiusRatio, 0.5));
+                    }
+                    if (params.points !== undefined)
+                        anyLayer.points = normalizePositiveInt(params.points, asFiniteNumber(anyLayer.points, 5), 3, 64);
+                    if (params.cornerRadius !== undefined)
+                        anyLayer.cornerRadius = normalizeCornerRadius(params.cornerRadius, asFiniteNumber(anyLayer.cornerRadius, 0));
+                }
+                else if (layer.type === 'line') {
+                    if (params.startX !== undefined)
+                        anyLayer.startX = cssPercentToX(params.startX, (asFiniteNumber(anyLayer.startX, -0.6) + 1) * 50);
+                    if (params.endX !== undefined)
+                        anyLayer.endX = cssPercentToX(params.endX, (asFiniteNumber(anyLayer.endX, 0.6) + 1) * 50);
+                    if (params.startY !== undefined)
+                        anyLayer.startY = cssPercentToY(params.startY, (1 - asFiniteNumber(anyLayer.startY, 0)) * 50);
+                    if (params.endY !== undefined)
+                        anyLayer.endY = cssPercentToY(params.endY, (1 - asFiniteNumber(anyLayer.endY, 0)) * 50);
+                    // Convenience sizing: adjust around 0 when width/height provided without explicit endpoints.
+                    if ((params.width !== undefined || params.height !== undefined) && params.startX === undefined && params.endX === undefined && params.startY === undefined && params.endY === undefined) {
+                        const prevHalfW = Math.max(0.01, Math.abs(asFiniteNumber(anyLayer.endX, 0.6) - asFiniteNumber(anyLayer.startX, -0.6)) / 2);
+                        const prevHalfH = Math.abs(asFiniteNumber(anyLayer.endY, 0) - asFiniteNumber(anyLayer.startY, 0)) / 2;
+                        const halfW = clamp(parseNumericInput(params.width), 0.01, 1, prevHalfW);
+                        const halfH = clamp(parseNumericInput(params.height), 0, 1, prevHalfH);
+                        anyLayer.startX = -halfW;
+                        anyLayer.endX = halfW;
+                        anyLayer.startY = -halfH;
+                        anyLayer.endY = halfH;
+                    }
+                }
+                // Keep transform scale at 1 for deterministic geometry sizing.
+                if (params.width !== undefined || params.height !== undefined || params.startX !== undefined || params.startY !== undefined || params.endX !== undefined || params.endY !== undefined) {
+                    layer.transform.width = 1;
+                    layer.transform.height = 1;
+                }
+            }
+            persistState();
             return {
                 content: [
                     {
@@ -1109,11 +2982,7 @@ async function handleStateTool(name, args) {
             };
         }
         case 'apply_effect': {
-            if (!currentPoster) {
-                return {
-                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
-                };
-            }
+            ensurePoster();
             const effectId = params.effectId;
             if (!effectId) {
                 return {
@@ -1122,6 +2991,7 @@ async function handleStateTool(name, args) {
             }
             if (effectId === 'none') {
                 delete currentPoster.effect;
+                persistState();
                 return {
                     content: [
                         {
@@ -1188,12 +3058,15 @@ async function handleStateTool(name, args) {
                 };
                 // Dither has BUILT-IN palette and bloom (WebGL pipeline)
                 // These don't use post-processes - settings are on the effect itself
+                const ditherPaletteId = params.paletteId ?? null;
+                const ditherDefaultColors = ['#000000', '#ffffff'];
+                // When paletteId is set, resolve to actual colors so the URL encodes them correctly
+                const ditherColors = params.colors ?? resolvePaletteColors(ditherPaletteId, ditherDefaultColors);
                 effect.dither = {
                     pattern: patternMap[effectId] || 'floydSteinberg',
                     pixelation: clamp(params.pixelation, 1, 20, 3),
-                    // Palette: use paletteId for built-in palette, or custom colors array
-                    paletteId: params.paletteId ?? null,
-                    colors: params.colors ?? ['#000000', '#ffffff'],
+                    paletteId: ditherPaletteId,
+                    colors: ditherColors,
                     brightness: clamp(params.brightness, 0, 2, 1),
                     contrast: clamp(params.contrast, 0.5, 2, 1.2),
                     threshold: 1.0,
@@ -1250,12 +3123,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 +3146,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,
@@ -1366,6 +3239,7 @@ async function handleStateTool(name, args) {
                 };
             }
             currentPoster.effect = effect;
+            persistState();
             return {
                 content: [
                     {
@@ -1380,11 +3254,7 @@ async function handleStateTool(name, args) {
             };
         }
         case 'add_postprocess': {
-            if (!currentPoster) {
-                return {
-                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
-                };
-            }
+            ensurePoster();
             const ppType = params.type;
             if (!ppType) {
                 return {
@@ -1430,6 +3300,18 @@ async function handleStateTool(name, args) {
                 'decay', // light-beams
                 'density', // light-beams
                 'particleAmount', // light-beams
+                // Blob tracking
+                'detection', // blob-tracking
+                'rectScale', // blob-tracking
+                'zoom', // blob-tracking
+                'invertChance', // blob-tracking
+                'animSpeed', // blob-tracking
+                'lineColor', // blob-tracking
+                'lineOpacity', // blob-tracking
+                'rectColor', // blob-tracking
+                'rectOpacity', // blob-tracking
+                'showLabels', // blob-tracking
+                'glow', // blob-tracking
             ];
             const allSettingKeys = [...commonKeys, ...additionalKeys];
             for (const key of allSettingKeys) {
@@ -1442,6 +3324,11 @@ async function handleStateTool(name, args) {
                 settings.type = settings.blurType;
                 delete settings.blurType;
             }
+            // Palette post-process: resolve paletteId to colors if colors weren't explicitly provided
+            if (ppType === 'palette' && settings.paletteId && !params.colors) {
+                const resolved = resolvePaletteColors(settings.paletteId, ['#000000', '#ffffff']);
+                settings.colors = resolved;
+            }
             const postProcess = {
                 id: ppId,
                 type: ppType,
@@ -1449,6 +3336,7 @@ async function handleStateTool(name, args) {
                 settings,
             };
             currentPoster.postProcesses.push(postProcess);
+            persistState();
             // Build response with warning if dither is active
             const response = {
                 success: true,
@@ -1471,11 +3359,7 @@ async function handleStateTool(name, args) {
             };
         }
         case 'remove_layer': {
-            if (!currentPoster) {
-                return {
-                    content: [{ type: 'text', text: 'Error: No poster created. Use create_poster first.' }],
-                };
-            }
+            ensurePoster();
             const layerId = params.layerId;
             if (!layerId) {
                 return {
@@ -1494,6 +3378,7 @@ async function handleStateTool(name, args) {
                 };
             }
             currentPoster.layers.splice(layerIndex, 1);
+            persistState();
             return {
                 content: [
                     {
@@ -1507,12 +3392,67 @@ async function handleStateTool(name, args) {
                 ],
             };
         }
-        case 'get_state': {
-            if (!currentPoster) {
+        case 'move_layer': {
+            ensurePoster();
+            const poster = currentPoster;
+            const layerId = params.layerId;
+            const direction = params.direction;
+            if (!layerId) {
                 return {
-                    content: [{ type: 'text', text: 'No poster created yet. Use create_poster first.' }],
+                    content: [{ type: 'text', text: 'Error: layerId is required' }],
                 };
             }
+            const layerIndex = poster.layers.findIndex((l) => l.id === layerId);
+            if (layerIndex < 0) {
+                return {
+                    content: [{ type: 'text', text: `Error: Layer not found: ${layerId}` }],
+                };
+            }
+            if (layerIndex === 0) {
+                return {
+                    content: [{ type: 'text', text: 'Error: Cannot move background layer' }],
+                };
+            }
+            const clampIndex = (index) => Math.max(1, Math.min(index, poster.layers.length - 1));
+            const moveTo = (toIndex) => {
+                const nextIndex = clampIndex(toIndex);
+                if (nextIndex === layerIndex)
+                    return false;
+                const [layer] = poster.layers.splice(layerIndex, 1);
+                poster.layers.splice(nextIndex, 0, layer);
+                return true;
+            };
+            let moved = false;
+            if (direction === 'up')
+                moved = moveTo(layerIndex + 1);
+            else if (direction === 'down')
+                moved = moveTo(layerIndex - 1);
+            else if (direction === 'top')
+                moved = moveTo(poster.layers.length - 1);
+            else if (direction === 'bottom')
+                moved = moveTo(1);
+            else {
+                return {
+                    content: [{ type: 'text', text: 'Error: direction must be one of: up, down, top, bottom' }],
+                };
+            }
+            persistState();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: moved ? `Layer moved (${direction})` : `Layer already at ${direction}`,
+                            layerId,
+                            totalLayers: poster.layers.length,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        case 'get_state': {
+            ensurePoster();
             return {
                 content: [
                     {