@devmotion/cli 0.6.3 → 0.8.0

package/mcp/mcp-stdio.mjs

@@ -32418,6 +32418,14 @@ var schema8 = size4.schema.extend({
   objectFit: external_exports3.enum(["contain", "cover", "fill", "none", "scale-down"]).default("cover").describe(
     "Fit mode: cover (crop to fill), contain (fit, may letterbox), fill (stretch), none (original size), scale-down."
   ).register(fieldRegistry, { interpolationFamily: "discrete", label: "Fit" }),
+  borderRadius: external_exports3.number().default(0).describe("Corner radius as % of project width. ~50% for circle crop.").register(fieldRegistry, {
+    interpolationFamily: "continuous",
+    label: "Radius",
+    postFix: "%",
+    step: 0.1,
+    min: 0,
+    max: 60
+  }),
   fileKey: external_exports3.string().default("").describe("Internal: S3 storage key for cleanup.").register(fieldRegistry, { hidden: true }),
   fileName: external_exports3.string().default("").describe("Internal: original filename for alt text.").register(fieldRegistry, { hidden: true }),
   attribution: external_exports3.object({
@@ -32861,27 +32869,39 @@ var AnchorPointSchema = external_exports3.enum([
   "bottom-center",
   "bottom-right"
 ]);
+var PositionSchema = external_exports3.object({
+  x: external_exports3.number().describe("X position as % of project width"),
+  y: external_exports3.number().describe("Y position as % of project width"),
+  z: external_exports3.number().describe("Z depth (px)")
+});
+var RotationSchema = external_exports3.object({
+  x: external_exports3.number().describe("X rotation (radians)"),
+  y: external_exports3.number().describe("Y rotation (radians)"),
+  z: external_exports3.number().describe("Z rotation (radians)")
+});
+var ScaleSchema = external_exports3.object({
+  x: external_exports3.number().min(0).describe("X scale (1 = normal)"),
+  y: external_exports3.number().min(0).describe("Y scale (1 = normal)")
+});
 var TransformSchema = external_exports3.object({
   // New nested format
-  position: external_exports3.object({
-    x: external_exports3.number().describe("X position as % of project width"),
-    y: external_exports3.number().describe("Y position as % of project width"),
-    z: external_exports3.number().describe("Z depth (px)")
-  }).optional().default({ x: 0, y: 0, z: 0 }),
-  rotation: external_exports3.object({
-    x: external_exports3.number().describe("X rotation (radians)"),
-    y: external_exports3.number().describe("Y rotation (radians)"),
-    z: external_exports3.number().describe("Z rotation (radians)")
-  }).optional().default({ x: 0, y: 0, z: 0 }),
-  scale: external_exports3.object({
-    x: external_exports3.number().min(0).describe("X scale (1 = normal)"),
-    y: external_exports3.number().min(0).describe("Y scale (1 = normal)")
-  }).optional().default({ x: 1, y: 1 }),
+  position: PositionSchema.optional().default({ x: 0, y: 0, z: 0 }),
+  rotation: RotationSchema.optional().default({ x: 0, y: 0, z: 0 }),
+  scale: ScaleSchema.optional().default({ x: 1, y: 1 }),
   anchor: AnchorPointSchema.describe("Transform pivot point on the layer").optional().default("center"),
   positionOrigin: AnchorPointSchema.describe(
     'Canvas reference for (0,0). Default "center" = (0,0) at canvas center. "top-left" = (0,0) at top-left corner.'
   ).optional().default("center")
 });
+var TransformPatchSchema = external_exports3.object({
+  position: PositionSchema.partial().optional(),
+  rotation: RotationSchema.partial().optional(),
+  scale: ScaleSchema.partial().optional(),
+  anchor: AnchorPointSchema.optional().describe("Transform pivot point on the layer"),
+  positionOrigin: AnchorPointSchema.optional().describe(
+    'Canvas reference for (0,0). Default "center" = (0,0) at canvas center. "top-left" = (0,0) at top-left corner.'
+  )
+});
 function defaultTransform() {
   return {
     position: { x: 0, y: 0, z: 0 },
@@ -33587,8 +33607,8 @@ function generateLayerTypePropsUnion() {
     layerSchemas.push(
       external_exports3.object({
         type: external_exports3.literal(layerType),
-        props: definition.schema.describe(
-          `${definition.label} layer. ${definition.description}. Sizes and positions in % of project width.`
+        props: definition.schema.partial().strict().optional().describe(
+          `${definition.label} layer. ${definition.description}. Provide only the props to set; omitted props use defaults (create) or keep current values (edit). Sizes and positions in % of project width.`
         )
       })
     );
@@ -33596,35 +33616,48 @@ function generateLayerTypePropsUnion() {
   return external_exports3.discriminatedUnion("type", layerSchemas);
 }
 var LayerTypePropsUnion = generateLayerTypePropsUnion();
-var CreateLayerAnimationSchema = external_exports3.object({
+var LayerAnimationSchema = external_exports3.object({
   preset: external_exports3.object({
     id: AnimationPresetIdSchema2.describe(
       "Animation preset ID (e.g., fade-in, slide-in-left, pop, bounce)"
     ),
     startTime: external_exports3.number().min(0).default(0).describe("When the animation begins (seconds)"),
-    duration: external_exports3.number().min(0.1).default(0.5).describe("How long the animation runs (seconds)")
+    duration: external_exports3.number().min(0.1).default(0.5).describe("How long the animation runs (seconds)"),
+    params: external_exports3.object({
+      distance: external_exports3.number().optional().describe("Distance for slide/reveal presets"),
+      intensity: external_exports3.number().optional().describe("Intensity for emphasis presets"),
+      fromScale: external_exports3.number().min(0).optional().describe("Starting scale for scale/pop presets")
+    }).optional().describe(
+      "Optional preset-specific parameters. Use only params listed in the preset catalog."
+    )
   }).optional().describe("Pre-built animation preset. Use for standard entrances/exits/emphasis."),
   keyframes: external_exports3.array(KeyframeSchema).optional().describe("Custom keyframes for precise animation control. Can be combined with a preset.")
 });
-var CreateLayerInputSchema = external_exports3.object({
-  name: external_exports3.string().optional().describe("Human-readable layer name"),
-  visible: external_exports3.boolean().default(true).describe("Whether the layer is visible (default: true)"),
-  locked: external_exports3.boolean().default(false).describe("Whether the layer is locked from editing (default: false)"),
-  // Transform (position, rotation, scale, anchor) — all in % of project width
-  transform: TransformSchema.describe(
-    "Position (% of project width), rotation (radians), scale (multiplier), anchor (pivot point). All fields optional with sensible defaults."
+var LayerStylePatchSchema = LayerStyleSchema.partial().optional().describe(
+  "Style patch: opacity, blur, brightness, contrast, saturation, drop shadow. Provide only the fields to change; omitted fields keep defaults (create) or current values (edit)."
+);
+var UpsertLayerInputSchema = external_exports3.object({
+  layerId: external_exports3.string().optional().describe(
+    "Omit to CREATE a new layer. Provide an existing layer ID (or name) to EDIT it \u2014 when editing, layer.type must match the target layer."
   ),
-  // Style (opacity, filters, shadows)
-  style: LayerStyleSchema.optional().describe(
-    "Visual style: opacity, blur, brightness, contrast, saturation, drop shadow"
+  name: external_exports3.string().optional().describe("Human-readable layer name"),
+  visible: external_exports3.boolean().optional().describe("Layer visibility (default on create: true)"),
+  locked: external_exports3.boolean().optional().describe("Lock the layer from editing (default on create: false)"),
+  // Transform deep patch — all in % of project width
+  transform: TransformPatchSchema.optional().describe(
+    "Transform patch: position (% of project width), rotation (radians), scale (multiplier), anchor (pivot), positionOrigin (canvas reference for (0,0)). Provide only fields to change."
   ),
+  // Style (opacity, filters, shadows) — patch semantics
+  style: LayerStylePatchSchema,
   // Timing
   ...TimingFieldsSchema.shape,
-  // Layer type and properties
-  layer: LayerTypePropsUnion,
+  // Layer type and properties (typed per layer type)
+  layer: LayerTypePropsUnion.optional().describe(
+    "Layer type + props. REQUIRED to create. For edits: provide it (with the matching type) when changing props; omit when only changing name/transform/style/timing/animation."
+  ),
   // Animation
-  animation: CreateLayerAnimationSchema.optional().describe(
-    "Optional animation: pick a preset for common effects or provide custom keyframes (or both)"
+  animation: LayerAnimationSchema.optional().describe(
+    "Optional animation: pick a preset for common effects and/or provide custom keyframes. On edit, keyframes are ADDED to the existing ones \u2014 use it to animate generated/imported media layers without recreating them."
   )
 }).refine(
   (data) => {
@@ -33634,63 +33667,19 @@ var CreateLayerInputSchema = external_exports3.object({
     return true;
   },
   { message: "enterTime must be less than exitTime", path: ["enterTime"] }
-);
-var EditLayerStyleSection = external_exports3.object({
-  opacity: external_exports3.number().min(0).max(1).optional(),
-  blur: external_exports3.number().min(0).optional(),
-  brightness: external_exports3.number().min(0).max(10).optional(),
-  contrast: external_exports3.number().min(0).max(10).optional(),
-  saturate: external_exports3.number().min(0).max(10).optional(),
-  dropShadowX: external_exports3.number().optional(),
-  dropShadowY: external_exports3.number().optional(),
-  dropShadowBlur: external_exports3.number().min(0).optional(),
-  dropShadowColor: external_exports3.string().optional()
-}).partial().optional().describe(
-  "Style to apply. Provide only the fields to change; omitted fields keep existing values."
-);
-var EditLayerTransformSection = TransformSchema.partial().optional().describe(
-  "Transform to apply. Provide only the fields to change; omitted fields keep existing values."
-);
-var EditLayerInputSchema = external_exports3.object({
-  layerId: external_exports3.string().describe("Layer ID (from create_layer) or layer name"),
-  // Basic fields
-  name: external_exports3.string().optional(),
-  visible: external_exports3.boolean().optional(),
-  locked: external_exports3.boolean().optional(),
-  // Transform section (replaces entirely if provided)
-  transform: EditLayerTransformSection,
-  // Style section (replaces entirely if provided)
-  style: EditLayerStyleSection,
-  // Anchor point
-  anchor: AnchorPointSchema.optional().describe("Anchor/pivot point for transforms"),
-  // Position origin
-  positionOrigin: AnchorPointSchema.optional().describe(
-    "Canvas corner/edge used as (0,0) reference. Default: center (0,0 = canvas center). Use top-left for (0,0) at top-left."
-  ),
-  // Props (merged with existing)
-  props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe(
-    "Layer-specific properties to update. Merged with existing props (not replaced). Validated server-side against the target layer's schema \u2014 unknown prop names or wrong types are rejected, so use the exact prop names from create_layer."
-  ),
-  // Timing fields
-  ...TimingFieldsSchema.shape
-}).refine(
-  (data) => {
-    if (data.enterTime !== void 0 && data.exitTime !== void 0) {
-      return data.enterTime < data.exitTime;
-    }
-    return true;
-  },
-  { message: "enterTime must be less than exitTime", path: ["enterTime"] }
-);
+).refine((data) => data.layerId !== void 0 || data.layer !== void 0, {
+  message: "layer (type + props) is required when creating (no layerId)",
+  path: ["layer"]
+});
 var RemoveLayerInputSchema = external_exports3.object({
-  layerId: external_exports3.string().describe("ID (from create_layer) or name of the layer to remove")
+  layerId: external_exports3.string().describe("ID (from upsert_layer) or name of the layer to remove")
 });
 var ConfigureProjectInputSchema = external_exports3.object({
   name: external_exports3.string().optional(),
   width: external_exports3.number().min(100).max(8192).optional(),
   height: external_exports3.number().min(100).max(8192).optional(),
   duration: external_exports3.number().min(1).max(300).optional(),
-  backgroundColor: external_exports3.string().optional().describe(
+  backgroundColor: BackgroundValueSchema.optional().describe(
     "Background: hex color string (e.g., #1a1a2e) or gradient object (see Background schema in system prompt)"
   )
 });
@@ -33927,16 +33916,88 @@ function layerNotFoundError(project, ref) {
     return `Layer "${ref}" not found. The project has no layers \u2014 create one first.`;
   }
   const available = project.layers.map((l) => `"${l.name}" (id: ${l.id})`).join(", ");
-  return `Layer "${ref}" not found. Use the exact layer id returned by create_layer, or reference existing layers by id/name. Available layers: ${available}`;
+  return `Layer "${ref}" not found. Use the exact layer id returned by upsert_layer, or reference existing layers by id/name. Available layers: ${available}`;
+}
+function mergeTransformPatch(base, patch) {
+  if (!patch) return base;
+  const merged = {
+    ...base,
+    position: { ...base.position },
+    rotation: { ...base.rotation },
+    scale: { ...base.scale }
+  };
+  if (patch.position) {
+    merged.position = { ...merged.position, ...patch.position };
+  }
+  if (patch.rotation) {
+    merged.rotation = { ...merged.rotation, ...patch.rotation };
+  }
+  if (patch.scale) {
+    merged.scale = { ...merged.scale, ...patch.scale };
+  }
+  if (patch.anchor !== void 0) {
+    merged.anchor = patch.anchor;
+  }
+  if (patch.positionOrigin !== void 0) {
+    merged.positionOrigin = patch.positionOrigin;
+  }
+  return merged;
+}
+function pickProvidedProps(inputProps, parsedProps) {
+  const patch = {};
+  for (const key of Object.keys(inputProps)) {
+    if (Object.prototype.hasOwnProperty.call(parsedProps, key) && parsedProps[key] !== void 0) {
+      patch[key] = parsedProps[key];
+    }
+  }
+  return patch;
+}
+function applyAnimation(project, layer, animation) {
+  if (!animation) return;
+  if (animation.preset) {
+    const presetKeyframes = getPresetKeyframes2(
+      animation.preset.id,
+      animation.preset.startTime ?? layer.enterTime ?? 0,
+      animation.preset.duration ?? 0.5,
+      { x: layer.transform.position.x, y: layer.transform.position.y },
+      animation.preset.params
+    );
+    for (const keyframe of presetKeyframes) {
+      addKeyframeToProject(project, layer.id, keyframe);
+    }
+  }
+  if (animation.keyframes) {
+    for (const kf2 of animation.keyframes) {
+      const interpolation = kf2.interpolation ?? {
+        family: "continuous",
+        strategy: "ease-in-out"
+      };
+      const clampedTime = Math.max(0, Math.min(kf2.time, project.duration));
+      addKeyframeToProject(project, layer.id, {
+        id: nanoid3(),
+        time: clampedTime,
+        property: kf2.property,
+        value: kf2.value,
+        interpolation
+      });
+    }
+  }
+}
+function mutateUpsertLayer(ctx, input) {
+  return input.layerId === void 0 || input.layerId === "" ? createLayerMutation(ctx, input) : editLayerMutation(ctx, input);
 }
-function mutateCreateLayer(ctx, input) {
+function createLayerMutation(ctx, input) {
   try {
+    if (!input.layer) {
+      const msg = "layer (type + props) is required to create a layer";
+      return { success: false, message: msg, error: msg };
+    }
     const layerData = input.layer;
     const layerType = layerData.type;
-    const layerProps = layerData.props;
+    const layerProps = layerData.props ?? {};
     const layer = createLayer(layerType, {
       props: layerProps,
-      transform: input.transform,
+      transform: mergeTransformPatch(defaultTransform(), input.transform),
       projectDimensions: {
         width: ctx.project.width,
         height: ctx.project.height
@@ -33967,54 +34028,23 @@ function mutateCreateLayer(ctx, input) {
       layer.contentOffset = input.contentOffset;
     }
     ctx.project.layers.push(layer);
-    if (input.animation) {
-      if (input.animation.preset) {
-        const presetKeyframes = getPresetKeyframes2(
-          input.animation.preset.id,
-          input.animation.preset.startTime ?? 0,
-          input.animation.preset.duration ?? 0.5,
-          { x: layer.transform.position.x, y: layer.transform.position.y }
-        );
-        for (const keyframe of presetKeyframes) {
-          addKeyframeToProject(ctx.project, layer.id, keyframe);
-        }
-      }
-      if (input.animation.keyframes) {
-        for (const kf2 of input.animation.keyframes) {
-          const interpolation = kf2.interpolation ?? {
-            family: "continuous",
-            strategy: "ease-in-out"
-          };
-          const clampedTime = Math.max(0, Math.min(kf2.time, ctx.project.duration));
-          addKeyframeToProject(ctx.project, layer.id, {
-            id: nanoid3(),
-            time: clampedTime,
-            property: kf2.property,
-            value: kf2.value,
-            interpolation
-          });
-        }
-      }
-    }
+    applyAnimation(ctx.project, layer, input.animation);
     return {
-      output: {
-        success: true,
-        layerId: layer.id,
-        layerName: layer.name,
-        message: `Created ${layerType} layer "${layer.name}"`
-      }
+      success: true,
+      created: true,
+      layerId: layer.id,
+      layerName: layer.name,
+      message: `Created ${layerType} layer "${layer.name}"`
     };
   } catch (err2) {
     return {
-      output: {
-        success: false,
-        message: "Failed to create layer",
-        error: err2 instanceof Error ? err2.message : "Unknown error"
-      }
+      success: false,
+      message: "Failed to create layer",
+      error: err2 instanceof Error ? err2.message : "Unknown error"
     };
   }
 }
-function mutateEditLayer(ctx, input) {
+function editLayerMutation(ctx, input) {
   const resolvedId = resolveLayerId(ctx.project, input.layerId);
   if (!resolvedId) {
     const errMsg = layerNotFoundError(ctx.project, input.layerId);
@@ -34029,6 +34059,10 @@ function mutateEditLayer(ctx, input) {
     };
   }
   const layer = ctx.project.layers[layerIndex];
+  if (input.layer && input.layer.type !== layer.type) {
+    const msg = `Layer "${layer.name}" is a ${layer.type} layer, but layer.type was "${input.layer.type}". Pass layer.type "${layer.type}" with its props, or omit layer when not changing props.`;
+    return { success: false, layerId: resolvedId, message: msg, error: msg };
+  }
   try {
     if (input.name !== void 0) {
       layer.name = input.name;
@@ -34040,30 +34074,28 @@ function mutateEditLayer(ctx, input) {
       layer.locked = input.locked;
     }
     if (input.transform) {
-      layer.transform = { ...layer.transform, ...input.transform };
-    }
-    if (input.anchor !== void 0) {
-      layer.transform.anchor = input.anchor;
-    }
-    if (input.positionOrigin !== void 0) {
-      layer.transform.positionOrigin = input.positionOrigin;
+      layer.transform = mergeTransformPatch(layer.transform, input.transform);
     }
     if (input.style) {
       layer.style = { ...layer.style, ...input.style };
     }
-    if (input.props) {
+    if (input.layer?.props) {
       const schema17 = getLayerSchemaData(layer.type);
-      const parsed = schema17.partial().safeParse(input.props);
+      const parsed = schema17.partial().strict().safeParse(input.layer.props);
       if (!parsed.success) {
         const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        const validProps = Object.keys(schema17.shape).join(", ");
         return {
           success: false,
           layerId: resolvedId,
-          message: `Invalid props for ${layer.type} layer "${layer.name}": ${detail}`,
+          message: `Invalid props for ${layer.type} layer "${layer.name}": ${detail}. Valid props for ${layer.type}: ${validProps}`,
           error: detail
         };
       }
-      layer.props = { ...layer.props, ...parsed.data };
+      layer.props = {
+        ...layer.props,
+        ...pickProvidedProps(input.layer.props, parsed.data)
+      };
     }
     if (input.enterTime !== void 0) {
       layer.enterTime = Math.max(0, input.enterTime);
@@ -34077,9 +34109,12 @@ function mutateEditLayer(ctx, input) {
     if (input.contentOffset !== void 0) {
       layer.contentOffset = Math.max(0, input.contentOffset);
     }
+    applyAnimation(ctx.project, layer, input.animation);
     return {
       success: true,
+      created: false,
       layerId: resolvedId,
+      layerName: layer.name,
       message: `Updated layer "${layer.name}"`
     };
   } catch (err2) {
@@ -34246,7 +34281,9 @@ function mutateConfigureProject(ctx, input) {
     }
     if (input.backgroundColor !== void 0) {
       ctx.project.background = input.backgroundColor;
-      changes.push(`background=${input.backgroundColor}`);
+      changes.push(
+        `background=${typeof input.backgroundColor === "string" ? input.backgroundColor : JSON.stringify(input.backgroundColor)}`
+      );
     }
     if (changes.length === 0) {
       return {
@@ -34274,15 +34311,195 @@ function addKeyframeToProject(project, layerId, keyframe) {
   }
 }
 
+// ../../src/lib/ai/design-knowledge.ts
+function presetProperties(preset) {
+  const props = preset.build({
+    distance: preset.defaults.distance ?? 2,
+    intensity: preset.defaults.intensity ?? 1,
+    fromScale: preset.defaults.fromScale ?? 0
+  }).map((k) => k.property);
+  return [...new Set(props)];
+}
+function presetLine(preset) {
+  const params = preset.params.length > 0 ? ` (params: ${preset.params.map((p) => `${p}=${preset.defaults[p]}`).join(", ")})` : "";
+  return `- ${preset.id}: animates ${presetProperties(preset).join(", ")}${params}`;
+}
+function presetCatalogSection() {
+  const byCategory = (cat) => PRESETS.filter((p) => p.category === cat).map(presetLine).join("\n");
+  return `## Animation Preset Catalog
+
+Use these preset IDs in upsert_layer's animation.preset.id. Presets are the
+fastest path to polished motion \u2014 prefer them over hand-written keyframes for
+standard entrances/exits, then add custom keyframes only for what presets
+don't cover. Combine: preset for entrance + custom keyframes for emphasis.
+
+### Entrances (use with startTime = layer enterTime)
+${byCategory("enter")}
+
+### Exits (set startTime so the preset ENDS at the layer exitTime)
+${byCategory("exit")}
+
+### Emphasis / loops (run mid-timeline, can repeat by chaining)
+${byCategory("generic")}`;
+}
+function designPlaybookSection() {
+  return `## Motion Design Playbook
+
+### What separates a good video from a flat one
+1. **One idea per moment** \u2014 never reveal more than one focal element at a time.
+2. **Layered backgrounds** \u2014 gradient base + 1-2 soft ambient shapes (blurred circles,
+   radius ~80-120, blur ~100-150, opacity 0.1-0.25) with slow position drift over the
+   whole duration. Flat solid backgrounds read as unfinished.
+3. **Staggered entrances** \u2014 when several elements enter, offset them by 0.12-0.25s
+   in reading order (top\u2192bottom or left\u2192right). Simultaneous entrances feel cheap.
+4. **Overlapping action** \u2014 start the next element's entrance before the previous
+   one fully settles (~70% through). Dead air between animations kills momentum.
+5. **Exits matter** \u2014 elements that vanish without an exit animation feel broken.
+   Pair every entrance preset with a matching exit (fade-in \u2192 fade-out,
+   slide-in-left \u2192 slide-out-right, scale-in \u2192 scale-out).
+6. **Scale restraint** \u2014 entrance scale from 0.92-0.96 \u2192 1 looks premium;
+   from 0 \u2192 1 looks cartoonish (reserve pop/bounce-in for playful content).
+7. **An accent color** \u2014 one saturated accent against a restrained palette.
+   Use the accent for the single most important element (CTA, key word, logo).
+
+### Scene archetypes (proven structures \u2014 instantiate, then customize)
+
+**Logo sting (2-4s)**: ambient background drift \u2192 logo/icon scale-in with
+ease-out-back at 0.0-0.6s \u2192 brand name reveal-up at 0.4-0.9s \u2192 tagline fade-in
+at 0.8-1.2s \u2192 hold \u2192 all fade-out in the last 0.5s.
+
+**Kinetic typography (1-2s per phrase)**: dark background, words enter one at a
+time with char-reveal or word-reveal on props.content, alternate entry directions
+per line (slide-in-left / slide-in-bottom), keyword in accent color at 1.3-1.6x
+the body size, previous line exits as the next enters.
+
+**Product showcase (5-8s)**: product image/video centered or right-of-center at
+55-70% width with scale-in \u2192 headline reveal-up in the title zone \u2192 2-3 feature
+lines staggered 0.2s each with slide-in-left \u2192 CTA button pop near the end with
+a pulse loop until exit.
+
+**Social hook (vertical 9:16, 3-5s)**: full-bleed media background \u2192 bold
+statement text (fontSize 6-9) center screen with pop or char-reveal in the first
+0.8s \u2192 supporting line below \u2192 captions word-by-word if there is speech.
+
+**Stat/data moment (2-3s per stat)**: huge number (fontSize 10-16) with quantized
+integer count-up keyframes (e.g. 0 \u2192 final value with @integer), label beneath in
+muted color, subtle shape behind (rounded rect, low-opacity accent).
+
+**Screen demo (variable)**: browser/laptop/phone frame layer with the recording
+inside \u2192 title card first 1-1.5s \u2192 mouse layer for pointer choreography \u2192
+zoom-in (scale 1 \u2192 1.4-1.8 with ease-in-out, position shifts toward the focus
+area) on the key interaction \u2192 captions for narration.
+
+### Pacing defaults
+- Entrances 0.3-0.6s, exits 0.2-0.4s, emphasis loops 0.8-1.5s per cycle.
+- Let content breathe: each text element should be fully readable for at least
+  1.2s + 0.05s per character before it exits.
+- End the video cleanly: either everything exits, or freeze on a composed final
+  frame \u2014 never cut mid-animation.
+- enterTime/exitTime are hard visibility cuts only. To create fades or
+  crossfades, add opacity keyframes or use fade presets; layer overlap alone is
+  not a crossfade.
+
+### Keyframe economy (keep tool calls small)
+- Presets are parameterized: fade-in/fade-out/scale-in with startTime, duration and
+  params cover entrances, exits and crossfades. Reach for custom keyframes only for
+  what no preset expresses (slow drifts, count-ups, color shifts).
+- A crossfade is two presets: fade-out ENDING at the outgoing layer's exitTime +
+  fade-in STARTING at the incoming layer's enterTime \u2014 not hand-written opacity arrays.
+- Keep custom keyframe arrays short (\u22643 keyframes per property). Long hand-written
+  arrays bloat the response and risk getting truncated mid-call.
+- Build complex scenes incrementally: a few tool calls per step, check results, continue.
+
+### Typography pairing
+- Hero: 5-9% width, weight 700-800, letterSpacing 0.
+- Subtitle: 2.5-3.5%, weight 400-500, muted color (60-75% opacity of text color).
+- Caption/label: 1.8-2.5%, optional uppercase + wide letterSpacing.
+- Mood: tech/dev \u2192 monospace; luxury/editorial \u2192 serif; default \u2192 geometric sans.`;
+}
+function narrationWorkflowSection(mode) {
+  const speechTool = mode === "chat" ? 'run_action with actionId "generate-speech"' : "action_generate_speech (voices via the list_tts_voices tool)";
+  return `## Narration / Voiceover Workflow
+
+To add spoken audio (voiceover, narration, character lines):
+1. Create the non-audio visual scene first when possible: background, subtle
+   ambient motion, typography/placeholders, and layout. This keeps the visible
+   composition from looking empty while the user approves credit-gated speech.
+2. Create an audio layer (upsert_layer, type "audio", empty src is fine) \u2014
+   name it after its role, e.g. "Voiceover".
+3. Call ${speechTool} with that layerId, the script text, and a voiceId from the
+   voice catalog. Voice IDs are case-sensitive; never invent a voiceId from
+   memory. If no TTS Voice Catalog is present, ask the user to choose a voice
+   before calling speech generation. The generated speech replaces the audio
+   layer's content.
+4. The speech result updates the audio layer with src/fileKey and usually
+   contentDuration/exitTime. Use that returned duration for the final project
+   duration when available; estimate at ~15 characters/second only before the
+   result arrives.
+5. For word-synced captions on generated narration, run generate-captions
+   directly on the same audio layer afterwards. Do not call analyze_media just
+   to get captions or duration for generated speech.
+6. Match caption style to the request in generate-captions params. For elegant
+   centered quote captions, use position "middle", mode "single-word" or
+   "highlight", a serif font such as "Playfair Display", fontWeight "400" or
+   "500", textColor near white, bgColor transparent/rgba when no pill highlight
+   is desired, and subtle shadow/outline only for readability.
+7. For standalone voiceover/quote requests, build the complete visual scene too:
+   intentional background, one subtle ambient motion element, and synced captions
+   or typography. Do not stop after generating audio.
+Write scripts for the ear: short sentences, no markup, numbers spelled out.`;
+}
+function assetProtocolSection(mode) {
+  const generate = mode === "chat" ? 'run_action with actionId "generate-image" (AI image) or "generate-video" (AI video), or "find-stock-image" (real stock photography)' : "action_generate_image (AI image), action_generate_video (AI video), or action_find_stock_image (real stock photography); users can also upload via upload_media/import_media";
+  return `## Asset Rules (CRITICAL)
+
+1. NEVER invent, guess, or placeholder a media URL. Image/video/audio layers with
+   fabricated src values render as broken files.
+2. Only use src URLs that come from: the Asset Library above, attached assets in
+   the conversation, tool results (generated/imported media), or URLs the user
+   explicitly provided.
+   In chat, run_action returns generated/imported layers in layersAdded[];
+   for image layers, layersAdded[].props.src is the real image source and
+   layersAdded[].props.fileKey is the storage key.
+3. When the request needs media you don't have (e.g. "make a video with my logo"
+   but no logo asset exists), do ONE of:
+   a. Ask the user to attach/upload the file, OR
+   b. Offer to create it: ${generate}.
+   State the options briefly and pick the obvious one when the user's intent is clear
+   (e.g. "a video about space" with no assets \u2192 generate or fetch stock, don't ask).
+4. When the user attaches images, they are uploaded as real assets \u2014 place them in
+   the composition with image layers using their src/fileKey, don't just describe them.
+5. Generated and stock media land in the Asset Library automatically; reuse them
+   instead of regenerating. If a generated/stock media layer already exists,
+   edit that layer for sizing, timing, transforms, opacity, and animation rather
+   than deleting and recreating it.`;
+}
+function buildDesignGuide() {
+  return `# DevMotion Design Guide
+
+How to produce polished animated videos with the DevMotion tools.
+Read once per session, before composing scenes.
+
+## Coordinate system
+All positions, sizes, font sizes, radii and stroke widths are % of project
+WIDTH (not pixels). (0,0) is the canvas center by default (positionOrigin:
+"center"); x ranges -50..+50. Layout in three zones: title (upper third),
+content (center), footer (lower third).
+
+${designPlaybookSection()}
+
+${presetCatalogSection()}
+
+${assetProtocolSection("mcp")}
+
+${narrationWorkflowSection("mcp")}`;
+}
+
 // ../../src/lib/server/mcp-tools.ts
 var mutationTools = {
-  create_layer: {
-    description: "Create a complete layer (type+props, transform, style, animation, timing). Sizes/positions in % of project width.",
-    inputSchema: CreateLayerInputSchema
-  },
-  edit_layer: {
-    description: "Modify a layer. Provide only fields to change. Transform/style replace entirely; props merge (validated against the layer schema).",
-    inputSchema: EditLayerInputSchema
+  upsert_layer: {
+    description: "Create a layer (omit layerId) or patch-edit an existing one (pass layerId; layer.type must match). Sizes/positions in % of project width. Provide only the fields to set/change.",
+    inputSchema: UpsertLayerInputSchema
   },
   remove_layer: {
     description: "Delete a layer by ID or name.",
@@ -34307,10 +34524,18 @@ function isErr(x) {
   return "isError" in x;
 }
 function registerDevmotionTools(server, deps) {
+  server.registerTool(
+    "get_design_guide",
+    {
+      description: "DevMotion design guide: motion design playbook, scene archetypes, the full animation preset catalog, and asset rules. Read this BEFORE composing scenes \u2014 it is what separates a polished video from a flat one.",
+      inputSchema: external_exports3.object({})
+    },
+    () => ok(buildDesignGuide())
+  );
   server.registerTool(
     "create_project",
     {
-      description: "Create a new animation project. In local mode, initialises the open project folder.",
+      description: "Create a new animation project. In local mode, initialises the open project folder. Tip: call get_design_guide before composing scenes.",
       inputSchema: external_exports3.object({
         name: external_exports3.string().default("Untitled Project"),
         width: external_exports3.number().default(720),
@@ -34383,11 +34608,8 @@ Use the project ID in subsequent tool calls.`
         const ctx = { project };
         let result;
         switch (name) {
-          case "create_layer":
-            result = mutateCreateLayer(ctx, toolInput);
-            break;
-          case "edit_layer":
-            result = mutateEditLayer(ctx, toolInput);
+          case "upsert_layer":
+            result = mutateUpsertLayer(ctx, toolInput);
             break;
           case "remove_layer":
             result = mutateRemoveLayer(ctx, toolInput);
@@ -34404,12 +34626,11 @@ Use the project ID in subsequent tool calls.`
           default:
             return err(`Unknown tool: ${name}`);
         }
-        const output = "output" in result ? result.output : result;
-        if (!(output.success ?? false)) {
-          return err(output.error || output.message || "Operation failed");
+        if (!(result.success ?? false)) {
+          return err(result.error || result.message || "Operation failed");
         }
         await adapter.saveProject(projectId, project);
-        return ok(JSON.stringify(output, null, 2));
+        return ok(JSON.stringify(result, null, 2));
       }
     );
   }