@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-motion-design/references/0-editframe.md

@@ -0,0 +1,299 @@
+---
+title: Implementing Motion in Editframe
+description: How the motion design principles map to Editframe syntax — CSS animations, --ef-progress, text splitting, addFrameTask, and transitions.
+type: explanation
+order: 0
+---
+
+# Implementing Motion in Editframe
+
+The motion design principles in this skill apply directly to Editframe's composition system. This reference maps each concept to the specific Editframe tools that implement it.
+
+---
+
+## Easing and Physics → CSS `animation-timing-function`
+
+The material physics model translates directly to CSS easing curves. Apply them to the `animation` shorthand on any element.
+
+```html
+<!-- Glass: clean entrance, minimal overshoot -->
+<ef-text style="animation: 400ms title-enter both; animation-timing-function: cubic-bezier(0, 0.55, 0.45, 1)">
+  Professional Title
+</ef-text>
+
+<!-- Rubber: bouncy entrance for playful brands -->
+<ef-text style="animation: 600ms logo-bounce both; animation-timing-function: cubic-bezier(0.68, -0.55, 0.265, 1.55)">
+  Fun Brand
+</ef-text>
+
+@keyframes title-enter {
+  from { transform: translateY(20px); opacity: 0; }
+  to   { transform: translateY(0);    opacity: 1; }
+}
+
+@keyframes logo-bounce {
+  from { transform: scale(0.8); opacity: 0; }
+  to   { transform: scale(1);   opacity: 1; }
+}
+```
+
+Add a new section after the material reference table:
+
+---
+
+## Rhythm Through Variation
+
+**Anti-pattern:** All animations using identical duration and easing creates mechanical, monotonous motion.
+
+**Rule:** Within any scene, vary at least ONE of: duration, easing, or delay pattern.
+
+**For keyboard/command-driven products (Linear, Raycast, etc.):**
+- Primary actions: 200-300ms, sharp easing (`cubic-bezier(0.55, 0, 1, 0.45)`) — feels responsive
+- State transitions: 400-500ms, smooth easing — shows the system working
+- Reveals/entrances: 500-600ms, gentle easing — gives content room to land
+
+```html
+<!-- Wrong: monotonous -->
+<ef-text style="animation: 0.6s enter ease-out">Action</ef-text>
+<ef-text style="animation: 0.6s enter ease-out">Result</ef-text>
+
+<!-- Right: rhythm through variation -->
+<ef-text style="animation: 0.25s snap cubic-bezier(0.55, 0, 1, 0.45)">⌘K</ef-text>
+<ef-text style="animation: 0.5s reveal ease-out 0.15s">Issue created</ef-text>
+```
+
+---
+
+## Stagger → `ef-text` `split` and `--ef-word-index`
+
+The attention sequencing principle — one focus at a time — is implemented through text splitting and CSS variable stagger delays.
+
+```html
+<!-- Word-by-word reveal with stagger -->
+<ef-text
+  split="word"
+  class="text-white text-4xl"
+  style="animation: 0.5s word-in both; animation-delay: calc(var(--ef-word-index) * 80ms)"
+>Your message builds word by word</ef-text>
+
+<!-- Character-by-character (typewriter style) -->
+<ef-text
+  split="char"
+  class="text-white text-3xl font-mono"
+  style="animation: 0.1s char-in both; animation-delay: calc(var(--ef-char-index) * 40ms)"
+>LOADING...</ef-text>
+
+<!-- Line-by-line with organic variation using --ef-seed -->
+<ef-text
+  split="line"
+  class="text-white text-2xl"
+  style="animation: 0.6s line-in both; animation-delay: calc(var(--ef-line-index) * 150ms); animation-timing-function: cubic-bezier(0, 0.55, calc(0.45 + var(--ef-seed) * 0.1), 1)"
+>First line
+Second line
+Third line</ef-text>
+
+@keyframes word-in  { from { transform: translateY(18px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+@keyframes char-in  { from { opacity: 0; }                               to { opacity: 1; }              }
+@keyframes line-in  { from { transform: translateY(12px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+```
+
+**Available CSS variables on split elements:**
+
+- `--ef-word-index` — 0-based index of this word in its parent
+- `--ef-char-index` — 0-based index of this character
+- `--ef-line-index` — 0-based index of this line
+- `--ef-stagger-offset` — total number of siblings (for inverse stagger: `calc((var(--ef-stagger-offset) - var(--ef-word-index)) * 80ms)`)
+- `--ef-seed` — stable random value per element, useful for organic variation
+
+---
+
+## Progress-Driven Animation → `--ef-progress`
+
+`--ef-progress` updates every frame to the current playback position (0–1) of its timegroup. This drives any CSS property as a continuous function of time.
+
+```html
+<!-- Bar that fills with time -->
+<ef-timegroup mode="fixed" duration="10s" class="w-full h-2 bg-slate-700">
+  <div class="h-full bg-blue-400" style="width: calc(var(--ef-progress) * 100%)"></div>
+</ef-timegroup>
+
+<!-- Color that shifts from cool to warm -->
+<ef-timegroup mode="fixed" duration="8s" class="w-full h-full"
+  style="background: hsl(calc(220 - var(--ef-progress) * 150), 70%, 50%)">
+</ef-timegroup>
+
+<!-- Counter that counts up -->
+<ef-timegroup mode="fixed" duration="5s" id="counter-scene">
+  <div id="count" class="text-white text-6xl font-bold">0</div>
+</ef-timegroup>
+<script>
+  const scene = document.getElementById('counter-scene');
+  const count = document.getElementById('count');
+  scene.addFrameTask((ownCurrentTimeMs, durationMs) => {
+    const progress = ownCurrentTimeMs / durationMs;
+    count.textContent = Math.floor(progress * 1000000).toLocaleString();
+  });
+</script>
+```
+
+**Other available time variables:**
+
+- `--ef-duration` — element's total duration as a CSS time value (e.g., `"8s"`)
+- `--ef-transition-duration` — overlap duration for scene transitions
+- `--ef-transition-out-start` — when fade-out should start (use as `animation-delay` for exits)
+
+---
+
+## Per-Frame Procedural Animation → `addFrameTask`
+
+For animations that can't be expressed with CSS — particle systems, generative graphics, data visualization, physics simulations — `addFrameTask` runs a callback every frame with the current time.
+
+```html
+<ef-timegroup mode="fixed" duration="6s" id="scene" class="w-full h-full bg-slate-900">
+  <canvas id="canvas" class="absolute inset-0 size-full"></canvas>
+</ef-timegroup>
+
+<script>
+  const scene = document.getElementById('scene');
+  const canvas = document.getElementById('canvas');
+  const ctx = canvas.getContext('2d');
+
+  scene.addFrameTask((ownCurrentTimeMs, durationMs) => {
+    canvas.width = canvas.offsetWidth;
+    canvas.height = canvas.offsetHeight;
+    const progress = ownCurrentTimeMs / durationMs;
+
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+    // Example: lines connecting to a center point, growing with progress
+    const cx = canvas.width / 2;
+    const cy = canvas.height / 2;
+    const count = Math.floor(progress * 60);
+
+    for (let i = 0; i < count; i++) {
+      const angle = (i / 60) * Math.PI * 2;
+      const radius = 200 + Math.sin(i * 0.5 + ownCurrentTimeMs * 0.001) * 40;
+      ctx.beginPath();
+      ctx.moveTo(cx, cy);
+      ctx.lineTo(cx + Math.cos(angle) * radius, cy + Math.sin(angle) * radius);
+      ctx.strokeStyle = `rgba(99, 179, 237, ${0.2 + progress * 0.5})`;
+      ctx.lineWidth = 1;
+      ctx.stroke();
+    }
+  });
+</script>
+```
+
+**Key rules for `addFrameTask`:**
+
+- The callback receives `(ownCurrentTimeMs, durationMs)` — local time, not global
+- Always resize the canvas inside the callback (`canvas.width = canvas.offsetWidth`) — this clears it
+- The callback runs on every frame during rendering, so it must be a pure function of `ownCurrentTimeMs`
+- No `Date.now()`, `Math.random()`, or any non-deterministic values — renders must be reproducible
+
+---
+
+## Overlapping Attention Choreography → `overlap` and CSS Delays
+
+Sequence elements with partially overlapping animations to create natural rhythm. The `overlap` attribute on `ef-timegroup` creates shared time between adjacent scenes; staggered `animation-delay` sequences elements within a scene.
+
+```html
+<!-- Within-scene sequencing: logo → headline → subhead -->
+<ef-timegroup mode="contain" duration="4s" class="absolute w-full h-full">
+  <!-- Logo arrives first -->
+  <ef-image src="logo.png" class="absolute top-8 left-8 w-32"
+    style="animation: 0.5s enter-down both 0s"></ef-image>
+
+  <!-- Headline starts before logo finishes (overlap 60%) -->
+  <ef-text class="absolute top-1/3 left-8 text-white text-5xl font-bold"
+    style="animation: 0.6s enter-up both 0.3s"></ef-text>
+
+  <!-- Subhead follows headline -->
+  <ef-text class="absolute top-1/2 left-8 text-white/70 text-2xl"
+    style="animation: 0.5s enter-up both 0.7s">Supporting text</ef-text>
+</ef-timegroup>
+
+@keyframes enter-down { from { transform: translateY(-16px); opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+@keyframes enter-up   { from { transform: translateY(16px);  opacity: 0; } to { transform: translateY(0); opacity: 1; } }
+```
+
+**Between-scene sequencing using `overlap`:**
+
+```html
+<!-- 1s overlap between scenes creates shared time for crossfade -->
+<ef-timegroup mode="sequence" overlap="1s">
+  <ef-timegroup mode="contain" class="absolute w-full h-full"
+    style="animation: 1s fade-out var(--ef-transition-out-start) both">
+    <!-- Scene A content -->
+  </ef-timegroup>
+  <ef-timegroup mode="contain" class="absolute w-full h-full"
+    style="animation: 1s fade-in both">
+    <!-- Scene B content -->
+  </ef-timegroup>
+</ef-timegroup>
+```
+
+---
+
+## Exit Animations → `--ef-transition-out-start`
+
+Exits should be shorter than entrances (30–40% shorter). Use `--ef-transition-out-start` to trigger exit animations at precisely the right moment, regardless of scene duration.
+
+```html
+<ef-timegroup mode="contain" duration="6s" class="absolute w-full h-full"
+  style="animation: 1s fade-out var(--ef-transition-out-start) both">
+
+  <!-- Elements exit before the scene ends (staggered out) -->
+  <ef-text class="absolute bottom-8 text-white text-4xl"
+    style="animation: 0.4s exit-down var(--ef-transition-out-start) both">Headline</ef-text>
+  <ef-text class="absolute bottom-4 text-white/70 text-xl"
+    style="animation: 0.4s exit-down calc(var(--ef-transition-out-start) - 0.1s) both">Subhead</ef-text>
+</ef-timegroup>
+
+@keyframes exit-down  { from { transform: translateY(0); opacity: 1; } to { transform: translateY(16px); opacity: 0; } }
+@keyframes fade-out   { from { opacity: 1; } to { opacity: 0; } }
+```
+
+`--ef-transition-out-start` is set automatically when `overlap` is used on the parent sequence. For scenes without a sequence parent, it equals `--ef-duration - <overlap>`.
+
+---
+
+## React Implementation
+
+In React, apply animations as inline `style` props:
+
+```tsx
+import { Timegroup, Text } from "@editframe/react";
+
+// Word stagger
+<Text
+  split="word"
+  className="text-white text-4xl font-bold"
+  style={{
+    animation: "0.5s word-in both",
+    animationDelay: "calc(var(--ef-word-index) * 80ms)"
+  }}
+>
+  Your message here
+</Text>
+
+// Progress-driven via addFrameTask on ref
+import { useRef, useEffect } from "react";
+
+const ProgressBar = () => {
+  const ref = useRef<HTMLElement>(null);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const bar = el.querySelector('.bar') as HTMLElement;
+    el.addFrameTask((t, d) => {
+      bar.style.width = `${(t / d) * 100}%`;
+    });
+  }, []);
+  return (
+    <Timegroup ref={ref} mode="fixed" duration="5s" className="w-full h-2 bg-slate-700">
+      <div className="bar h-full bg-blue-400 transition-none" />
+    </Timegroup>
+  );
+};
+```

package/dist/skills/editframe-motion-design/references/1-intent.md

@@ -0,0 +1,201 @@
+---
+title: Intent
+description: Define motion intent by mapping message and emotional goal to specific motion characteristics before choosing timing or easing.
+type: explanation
+order: 1
+---
+
+# Intent → Strategy
+
+## Core Concept
+
+**Message + Emotion → Motion Characteristics**
+
+Every animation starts with intent. Before choosing timing or easing, determine what the viewer should feel and remember.
+
+## The Intent Framework
+
+### 1. Extract the Core Message
+
+What's the single most important thing?
+
+**Good intent statements:**
+- "User action succeeded, continue with confidence"
+- "This content is important, pay attention"
+- "Loading is happening, please wait briefly"
+- "These items are related and sequential"
+
+**Bad intent statements:**
+- "Make it look cool" (no communication goal)
+- "Add some animation" (no purpose)
+- "Fade in the elements" (mechanism, not intent)
+
+### 2. Determine Target Emotion
+
+The emotion directly maps to motion characteristics:
+
+| Emotion | Timing | Easing | Material | Exaggeration |
+|---------|--------|--------|----------|--------------|
+| Playful | Fast (250ms) | Bounce | Rubber | High (120%) |
+| Confident | Medium (400ms) | Smooth | Metal/Glass | Low (102%) |
+| Calm | Slow (800ms) | Gentle | Paper/Wood | Minimal (101%) |
+| Urgent | Very fast (200ms) | Sharp | Stone/Metal | None |
+| Premium | Slow (600ms) | Fluid | Leather/Glass | Subtle (103%) |
+| Friendly | Medium (350ms) | Slight bounce | Plastic | Moderate (105%) |
+
+### 3. Context Modifiers
+
+**Viewing Context:**
+- Social media (mobile): Fast (200-400ms), attention-grabbing
+- Explainer video: Medium (500-800ms), clear and readable
+- Cinematic: Slow (1000-1600ms), dramatic
+- Ads: Fast to medium, hook within 3 seconds
+
+**Content Type:**
+- Tutorial: Slower, more explanatory
+- Entertainment: Fast-paced, energetic
+- Documentary: Medium, measured
+- Promotional: Fast, exciting
+
+**Viewing Frequency:**
+- One-time narrative: Can be longer, more detailed
+- Looping content: Must loop seamlessly, can't become annoying
+- Repeated branding: Very brief, memorable
+- Background ambient: Subtle, non-distracting
+
+### 4. Communication vs Decoration Test
+
+**Ask:** If I remove this animation, does the message weaken?
+
+**Communication** (keep):
+- Directs viewer attention to key information
+- Shows relationships between concepts
+- Emphasizes important moments
+- Guides narrative flow
+- Clarifies transitions between ideas
+
+**Decoration** (remove):
+- Makes things "look pretty" without purpose
+- Distracts from core message
+- Adds time without adding clarity
+- Becomes tiresome on repeated viewing
+
+## Mapping Intent to Physics Model
+
+Once intent is clear, it determines material selection:
+
+**Intent:** User succeeded, feel confident and rewarded
+→ **Emotion:** Confident + slight celebration
+→ **Material:** Glass with slight rubber (mostly rigid, tiny bounce)
+→ **Physics:** 400ms, 5% overshoot, ease-out
+
+**Intent:** Loading in progress, maintain attention without anxiety
+→ **Emotion:** Calm, patient
+→ **Material:** Liquid (continuous, flowing)
+→ **Physics:** 1400ms loop, ease-in-out, smooth
+
+**Intent:** Error occurred, immediate attention needed
+→ **Emotion:** Urgent, alerting
+→ **Material:** Metal (sharp, immediate)
+→ **Physics:** 400ms, sharp shake, no bounce
+
+## Output Format
+
+Before implementing any animation, write:
+
+```
+Intent: [What should viewer remember/feel/do?]
+Emotion: [Target feeling]
+Material: [Physical metaphor]
+Exaggeration: [Subtle/Moderate/High]
+Context: [Platform, frequency, user state]
+
+Result: [Concrete motion characteristics]
+```
+
+**Example:**
+
+```
+Intent: Emphasize key statistic in explainer video
+Emotion: Confident, clear
+Material: Glass with 5% rubber bounce
+Exaggeration: Subtle (103%)
+Context: Explainer video, one-time viewing, general audience
+
+Result:
+- Duration: 600ms (18 frames at 30fps)
+- Scale: 1 → 1.03 → 1
+- Position: Slide in from right (60px)
+- Easing: ease-out
+```
+
+## Common Intent Patterns for Video
+
+### Narrative Flow Intents
+
+**"Introducing new section"**
+→ Clear transition (500-800ms), wipe or dissolve
+→ Material: Paper or glass (clean, professional)
+
+**"Key point emphasis"**
+→ Scale + position (400-600ms), draws eye
+→ Material: Stone (substantial) or metal (sharp)
+
+**"Supporting information"**
+→ Subtle fade-in (300-400ms), doesn't steal focus
+→ Material: Paper (light, secondary)
+
+### Brand/Title Intents
+
+**"Logo reveal"**
+→ Memorable entrance (800-1200ms), can be playful or serious
+→ Material: Rubber (playful) or glass (professional)
+
+**"Title card"**
+→ Clear, readable (600-1000ms), establishes hierarchy
+→ Material: Depends on brand personality
+
+**"End card/CTA"**
+→ Attention-grabbing (500-800ms), clear next action
+→ Material: Metal (urgent) or glass (confident)
+
+### Transition Intents
+
+**"Scene change, different context"**
+→ Clear break (400-600ms), wipe or cut
+→ Material: Metal (sharp) or stone (definitive)
+
+**"Scene change, same context"**
+→ Smooth flow (600-800ms), dissolve or fade
+→ Material: Liquid (flowing) or paper (gentle)
+
+**"Time passage"**
+→ Dissolve or clock-like (800-1200ms)
+→ Material: Liquid (smooth, continuous)
+
+## Anti-Patterns
+
+### Intent Drift
+
+Starting with clear intent but adding motion that contradicts it:
+
+**Intent:** "Quick confirmation without disrupting workflow"
+**Bad implementation:** 2-second celebration animation with particles
+
+The implementation violated the intent (quick, non-disruptive).
+
+### Multiple Simultaneous Intents
+
+Trying to communicate several things at once:
+
+**Bad:** Sidebar slides in WHILE content fades in WHILE header animates
+**Result:** Viewer doesn't know where to look, misses all three messages
+
+**Fix:** Sequence them. One intent at a time.
+
+### Implied vs Stated Intent
+
+**Implied:** "Make the button feel more premium"
+**Stated:** "User should feel confident their payment is secure"
+
+Always state intent explicitly. Implied intents drift toward decoration.