@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/videos/.builder/ANIMATED_PROPERTIES.md

@@ -1,335 +0,0 @@
-# Animated Properties System
-
-## Overview
-
-The Video Studio interactive component system supports **ANY CSS property** for hover and click animations. This means you can animate absolutely anything - colors, sizes, transforms, filters, borders, and more!
-
-## Quick Start
-
-### 1. Make Your Component Interactive
-
-```tsx
-import { useInteractiveComponent } from "@/remotion/hooks/useInteractiveComponent";
-import { AnimatedElement } from "@/remotion/components/AnimatedElement";
-
-const MyComp = ({ cursorHistory }) => {
-  const button = useInteractiveComponent({
-    id: "my-button",
-    elementType: "Button",
-    label: "My Button",
-    compositionId: "my-comp",
-    zone: { x: 100, y: 100, width: 200, height: 60 },
-    cursorHistory,
-    interactiveElementType: "button",
-  });
-
-  registerForCursor(button);
-
-  return (
-    <AnimatedElement interactive={button} as="button">
-      Click me!
-    </AnimatedElement>
-  );
-};
-```
-
-### 2. Add Animations via UI
-
-1. Hover over the element in the video player
-2. Open the "Cursor Interactions" panel (automatically appears)
-3. Click "+ Add Hover Animation" or "+ Add Click Animation"
-4. Add properties: **backgroundColor**, **scale**, **borderRadius**, etc.
-5. See your changes in real-time!
-
-## Supported Properties
-
-### ✅ ALL CSS Properties Work!
-
-The `AnimatedElement` component automatically converts animated properties to appropriate CSS styles. Here are some examples:
-
-#### Transform Properties
-
-- `scale` → `transform: scale()`
-- `translateX`, `translateY`, `translateZ` → `transform: translate()`
-- `rotate`, `rotateX`, `rotateY`, `rotateZ` → `transform: rotate()`
-- `skewX`, `skewY` → `transform: skew()`
-
-#### Filter Properties
-
-- `blur` → `filter: blur()`
-- `brightness` → `filter: brightness()`
-- `contrast` → `filter: contrast()`
-- `saturate` → `filter: saturate()`
-- `hueRotate` → `filter: hue-rotate()`
-
-#### Color Properties
-
-- `backgroundColor` or `background`
-- `color` or `textColor`
-- `borderColor`
-
-#### Size Properties
-
-- `width`, `height`
-- `padding`, `margin`
-- `borderWidth`
-- `borderRadius`
-
-#### Shadow & Effects
-
-- `boxShadow` or `shadow`
-- `opacity`
-
-#### Custom Properties
-
-- **ANY** kebab-case CSS property name (e.g., `font-size`, `line-height`)
-- **ANY** camelCase CSS property name (e.g., `fontSize`, `lineHeight`)
-
-## How AnimatedElement Works
-
-The `AnimatedElement` component:
-
-1. **Reads** all animated properties from the interactive component state
-2. **Converts** them to inline CSS styles automatically
-3. **Handles** transforms, filters, and all CSS properties intelligently
-4. **Merges** with any additional styles you provide
-5. **Applies** everything to the rendered element
-
-### Under the Hood
-
-```tsx
-// User adds "backgroundColor" animation from #000000 to #FFFFFF via UI
-
-// AnimatedElement automatically:
-// 1. Detects backgroundColor property
-// 2. Interpolates value based on hover progress (0 → 1)
-// 3. Applies as inline style: backgroundColor: "#888888" (at 50% hover)
-```
-
-## Advanced Usage
-
-### Custom Components
-
-```tsx
-// Works with ANY component that accepts style prop
-<AnimatedElement interactive={myButton} as={CustomButton} customProp="value">
-  Content
-</AnimatedElement>
-```
-
-### Merge with Static Styles
-
-```tsx
-// User-provided styles override animated styles
-<AnimatedElement
-  interactive={myButton}
-  as="div"
-  style={{
-    backgroundColor: "red", // This overrides animated backgroundColor
-    position: "absolute", // Static styles work fine
-  }}
->
-  Content
-</AnimatedElement>
-```
-
-### Manual Property Extraction
-
-If you need custom logic, extract properties manually:
-
-```tsx
-const button = useInteractiveComponent({ ... });
-
-const scale = (button.animatedProperties?.scale as number) ?? 1;
-const bgColor = button.animatedProperties?.backgroundColor ?? "transparent";
-const customProp = button.animatedProperties?.myCustomProperty;
-
-<div style={{
-  transform: `scale(${scale})`,
-  backgroundColor: bgColor,
-  // Custom logic here
-}}>
-  Content
-</div>
-```
-
-## Examples
-
-### Background Color Hover
-
-Via UI:
-
-1. Select element
-2. Add hover animation
-3. Add property: `backgroundColor`
-4. From: `rgba(0,0,0,0.1)`, To: `rgba(0,0,0,0.3)`
-
-### Multi-Property Animation
-
-Via UI:
-
-1. Select element
-2. Add hover animation
-3. Add properties:
-   - `scale`: From `1`, To `1.05`
-   - `backgroundColor`: From `#f0f0f0`, To `#ffffff`
-   - `borderRadius`: From `8px`, To `16px`
-   - `boxShadow`: From `0 2px 4px rgba(0,0,0,0.1)`, To `0 8px 16px rgba(0,0,0,0.2)`
-
-All properties animate smoothly together!
-
-### Click Feedback
-
-Via UI:
-
-1. Select element
-2. Add click animation (duration: 6 frames)
-3. Add properties:
-   - `scale`: From `1`, To `0.95`
-   - `brightness`: From `100%`, To `90%`
-
-Element "presses down" on click!
-
-## Property Types
-
-### Number Properties
-
-- Automatically adds `px` for size properties (width, padding, etc.)
-- Automatically adds `deg` for rotation properties
-- Automatically adds `%` for filter properties (brightness, contrast)
-
-### String Properties
-
-- Used as-is for colors, shadows, etc.
-- Example: `#ff0000`, `rgba(0,0,0,0.5)`, `0 4px 8px rgba(0,0,0,0.2)`
-
-### Units
-
-When adding properties via UI, include units in the value:
-
-- `10px` ✅
-- `50%` ✅
-- `1.5em` ✅
-- `10` ⚠️ (interpreted as pixels for size properties)
-
-## Best Practices
-
-### 1. Use AnimatedElement by Default
-
-```tsx
-// ✅ RECOMMENDED - Works with ANY property
-<AnimatedElement interactive={button} as="button">
-  Click me
-</AnimatedElement>
-
-// ❌ MANUAL - Requires updating code for each property
-<button style={{
-  transform: `scale(${scale})`,
-  // Forgot to add backgroundColor? Need to update code!
-}}>
-  Click me
-</button>
-```
-
-### 2. Keep Animations Subtle
-
-- Hover scale: 1.05 - 1.15 (not 2.0!)
-- Lift: 4px - 12px (not 50px!)
-- Color shifts: Slight variations (not black → white!)
-
-### 3. Use Appropriate Durations
-
-- Hover: 6-12 frames (fast, responsive)
-- Click: 3-6 frames (immediate feedback)
-- Complex: 12-24 frames (smooth, elegant)
-
-### 4. Test on Actual Hardware
-
-- What looks good at 60fps may feel sluggish at 30fps
-- Test hover responsiveness with real mouse movement
-- Check click feedback feels immediate
-
-## Troubleshooting
-
-### Properties Not Applying?
-
-**Check:**
-
-1. ✅ Using `AnimatedElement` component?
-2. ✅ Passing `interactive` prop correctly?
-3. ✅ Registered component with `registerForCursor()`?
-4. ✅ Property name matches exactly (case-sensitive)?
-
-### Common Mistakes
-
-**Wrong:** Using className instead of inline styles in Remotion
-
-```tsx
-<AnimatedElement interactive={button} className="hover:bg-red-500">
-  Won't work - Remotion doesn't support className animations
-</AnimatedElement>
-```
-
-**Right:** AnimatedElement handles everything
-
-```tsx
-<AnimatedElement interactive={button}>
-  Works - animatedProperties applied as inline styles!
-</AnimatedElement>
-```
-
-### Debugging
-
-Log animated properties to see what's available:
-
-```tsx
-console.log(button.animatedProperties);
-// Output: { scale: 1.05, backgroundColor: "#ffffff", ... }
-```
-
-## Architecture
-
-### Data Flow
-
-```
-User hovers over element
-  ↓
-useInteractiveComponent detects hover
-  ↓
-Retrieves animations from CurrentElementContext
-  ↓
-Calculates property values at current hover progress
-  ↓
-Stores in animatedProperties object
-  ↓
-AnimatedElement reads animatedProperties
-  ↓
-Converts to inline styles
-  ↓
-Applies to rendered element
-```
-
-### Storage
-
-Animations are stored in:
-
-- `CurrentElementContext` - In-memory state
-- `localStorage` - Persistent across reloads (per-composition)
-
-### Interpolation
-
-Property values are interpolated using:
-
-- Easing functions (expo.out, power2.inOut, etc.)
-- Progress value (0 → 1 for hover/click)
-- Keyframes (from → to values)
-
-## Summary
-
-✅ **ANY CSS property can be animated**  
-✅ **Use AnimatedElement for automatic application**  
-✅ **Add properties via UI - no code changes needed**  
-✅ **Works with transforms, filters, colors, sizes, and more**  
-✅ **Fully customizable and extensible**
-
-The animated properties system is designed to be **completely flexible**. If you can style it with CSS, you can animate it in Video Studio!

package/corpus/templates/videos/.builder/KEYFRAME_SYNC.md

@@ -1,166 +0,0 @@
-# Keyframe Sync Prevention Guide
-
-## The Problem
-
-When a composition is first loaded, it saves track data (including `keyframes: []`) to `localStorage`. If you later add keyframes to the registry, the localStorage version (with empty keyframes) was overriding the registry version.
-
-## Safeguards Now in Place
-
-### 1. **Smart Merge Logic** ✅
-
-`app/contexts/TimelineContext.tsx` now intelligently merges keyframes:
-
-```typescript
-// If localStorage has empty keyframes but registry has keyframes, use registry
-const useRegistryKeyframes =
-  (!storedProp.keyframes || storedProp.keyframes.length === 0) &&
-  defProp.keyframes &&
-  defProp.keyframes.length > 0;
-```
-
-**Result**: Adding keyframes to the registry will automatically work on next reload.
-
-### 2. **Console Validation Warnings** ✅
-
-When keyframes are defined in registry but not showing in timeline, you'll see:
-
-```
-⚠️ Registry has keyframes but they're not showing in the timeline!
-Composition: ui-showcase
-Fix: Run in console: localStorage.removeItem('videos-tracks:ui-showcase'); location.reload();
-```
-
-### 3. **Developer Reset Utilities** ✅
-
-Available in browser console:
-
-```javascript
-// Reset the current composition
-resetCurrent();
-
-// Reset just keyframes/tracks for a specific composition
-resetTracks("ui-showcase");
-
-// Reset everything (tracks, props, settings)
-resetCompositionSettings("ui-showcase");
-```
-
-**Pro tip**: These are automatically loaded and available in `window`.
-
-### 4. **Detailed Logging** ✅
-
-When keyframes are loaded from registry, you'll see:
-
-```
-🔄 Using registry keyframes for "x" (9 keyframes from code)
-```
-
-This confirms the merge is working correctly.
-
-### 5. **Comprehensive Documentation** ✅
-
-- Registry file (`app/remotion/registry.ts`) has detailed header docs
-- Reset utility (`app/utils/resetComposition.ts`) explains usage
-- This guide! 📖
-
-## Best Practices
-
-### ✅ DO:
-
-- **Define keyframes in registry from the start** when creating new compositions
-- **Use resetTracks() during development** when testing new keyframes
-- **Check browser console** for validation warnings
-- **Save button preserves keyframes** - using the Save button writes current keyframes to registry
-
-### ❌ DON'T:
-
-- Don't manually edit localStorage (use reset utilities instead)
-- Don't assume keyframes will auto-update without a reset (they will on _next_ fresh load, but existing localStorage needs clearing)
-
-## Quick Fixes
-
-### "I added keyframes but don't see them"
-
-**Option 1**: Console reset (instant)
-
-```javascript
-resetTracks("your-composition-id");
-// then refresh page
-```
-
-**Option 2**: Manual localStorage clear
-
-```javascript
-localStorage.removeItem("videos-tracks:your-composition-id");
-location.reload();
-```
-
-**Option 3**: Hard refresh
-
-- Close all tabs with the app open
-- Open in new tab/window
-- Should auto-sync on first load
-
-### "I want to test keyframes without affecting users"
-
-1. Use a different composition ID during development:
-
-   ```typescript
-   id: "ui-showcase-dev"; // Test version
-   ```
-
-2. Once finalized, rename back to production ID:
-
-   ```typescript
-   id: "ui-showcase"; // Production version
-   ```
-
-3. Users will get fresh keyframes on first load of the new ID
-
-## Technical Details
-
-### Merge Priority (from highest to lowest):
-
-1. **User-created keyframes** (manually added in timeline) → Always preserved
-2. **Registry keyframes** → Used if localStorage has empty array
-3. **Empty array** → Only if both stored and registry are empty
-
-### When Keyframes Sync:
-
-- ✅ New composition loaded for first time
-- ✅ localStorage cleared via reset utilities
-- ✅ Registry keyframes added when localStorage has empty array
-- ❌ Automatic sync when localStorage already has empty array (use reset)
-
-### Cross-Tab Sync:
-
-Changes are automatically synced across tabs via `storage` event listeners. If you reset in one tab, other tabs will pick up the changes.
-
-## Testing Checklist
-
-When adding new keyframes to a composition:
-
-- [ ] Add keyframes to registry track definition
-- [ ] Test in browser console: `resetTracks('composition-id')`
-- [ ] Verify keyframes appear in timeline
-- [ ] Play composition to test animation
-- [ ] Check console for any warnings
-- [ ] Document in composition description if this changes existing behavior
-
-## Future Improvements
-
-Potential enhancements to consider:
-
-1. **Version tracking**: Add version number to tracks in registry, auto-reset if version changes
-2. **UI indicator**: Show badge when registry has newer keyframes than localStorage
-3. **Auto-migration**: Prompt user to reset when keyframe mismatch detected
-4. **Dev mode**: Flag to always prefer registry over localStorage during development
-
----
-
-**Last Updated**: March 2, 2026  
-**Related Files**:
-
-- `app/contexts/TimelineContext.tsx` (merge logic)
-- `app/utils/resetComposition.ts` (reset utilities)
-- `app/remotion/registry.ts` (composition definitions)

package/corpus/templates/videos/.builder/SEAMLESS_SYNC.md

@@ -1,211 +0,0 @@
-# Seamless Registry-LocalStorage Sync System
-
-## ✅ What's Implemented
-
-### 1. **Visual Save Button States**
-
-**🟢 Green Save Button** = You have unsaved changes
-
-- localStorage has overrides that differ from registry
-- Click to sync your changes to registry
-- Shows tooltip: "Save current settings as default"
-
-**⚪ Grey Save Button** = Everything is synced
-
-- No localStorage overrides
-- Registry and working state are identical
-- Shows tooltip: "All changes saved to registry"
-
-**Implementation**: `useUnsavedChanges()` hook detects localStorage presence
-
-### 2. **Auto-Save After AI Generation**
-
-When AI creates or modifies a composition:
-
-1. AI finishes (fires `builder.agentChat.chatRunning` event with `isRunning: false`)
-2. System waits 1 second for localStorage to settle
-3. **Automatically saves to registry** (silent mode, no alerts)
-4. Clears localStorage
-5. Reloads page with clean registry defaults
-6. 🟢 **Save button turns grey** (everything synced!)
-
-**Flow**:
-
-```
-User asks AI to change composition
-  ↓
-AI makes changes (auto-saves to localStorage)
-  ↓
-AI finishes (event fires)
-  ↓
-System auto-saves to registry (silent)
-  ↓
-localStorage cleared
-  ↓
-Page reloads
-  ↓
-✅ Registry and localStorage in perfect sync!
-```
-
-### 3. **Orange Indicator + Reset Button**
-
-Still shows when you have localStorage overrides, but:
-
-- Now correctly disappears after Save
-- Perfectly syncs with Save button color
-- One-click reset available
-
-## 🎯 Complete User Experience
-
-### Scenario 1: Manual Editing
-
-```
-1. User edits composition
-   🟡 Orange indicator appears
-   🟢 Save button turns green
-
-2. User clicks Save
-   ✅ Confirmation dialog
-   ✅ Saves to registry
-   ✅ Clears localStorage
-   ✅ Reloads page
-
-3. After reload:
-   ⚪ No orange indicator
-   ⚪ Grey Save button
-   ✅ Perfect sync!
-```
-
-### Scenario 2: AI Generation
-
-```
-1. User asks AI to create composition
-   🤖 AI generates code
-   🟡 Changes auto-save to localStorage
-   🟢 Save button green
-
-2. AI finishes
-   🤖 Auto-save triggers (silent)
-   ✅ Saves to registry
-   ✅ Clears localStorage
-   ✅ Reloads page
-
-3. After reload:
-   ⚪ No orange indicator
-   ⚪ Grey Save button
-   ✅ Perfect sync automatically!
-```
-
-### Scenario 3: Version Bump
-
-```
-Developer adds keyframes to registry:
-
-1. Increment version: 2
-2. User loads composition
-   🔄 Auto-detects version mismatch
-   🔄 Clears stale localStorage
-   ✅ Loads fresh registry defaults
-   ⚪ Grey Save button (synced)
-```
-
-## 🛠️ Technical Details
-
-### Files Modified:
-
-**`app/hooks/useUnsavedChanges.ts`** (NEW)
-
-- Hook that detects localStorage presence
-- Returns `true` if unsaved changes exist
-- Reactively updates when storage changes
-
-**`app/pages/CompositionView.tsx`**
-
-- Uses `useUnsavedChanges()` hook
-- Save button styling: `hasUnsavedChanges ? green : grey`
-- Refactored save into `performSave(silent)` function
-- Listens for `videos.auto-save` event
-- Auto-saves silently after AI generation
-
-**`app/components/NewCompositionPopover.tsx`**
-
-- Listens for `builder.agentChat.chatRunning` event
-- Dispatches `videos.auto-save` when AI finishes
-- Waits 1 second for localStorage to settle
-
-**`app/contexts/TimelineContext.tsx`**
-
-- Version tracking system
-- Smart keyframe merge (registry wins when localStorage empty)
-- Auto-clear stale data on version mismatch
-- Comprehensive logging
-
-**`app/remotion/registry.ts`**
-
-- Added `version?` field to `CompositionEntry`
-- Documented keyframe sync patterns
-- UI Showcase uses `version: 3`
-
-### Console Commands Available:
-
-```javascript
-// Reset current composition
-resetCurrent();
-
-// Reset only tracks/keyframes
-resetTracks("composition-id");
-
-// Reset everything
-resetCompositionSettings("composition-id");
-```
-
-## 📊 State Machine
-
-```
-Registry (Source of Truth)
-    ↓
-localStorage (Working Copy)
-    ↓ (user edits)
-localStorage (Modified)
-    🟢 Green Save + 🟡 Orange indicator
-    ↓ (click Save OR AI finishes)
-Registry (Updated)
-    ↓ (localStorage cleared)
-    ⚪ Grey Save + No indicator
-```
-
-## 🎨 Visual Indicators at a Glance
-
-| State      | Save Button | Orange Indicator | Meaning                  |
-| ---------- | ----------- | ---------------- | ------------------------ |
-| Synced     | Grey ⚪     | Hidden           | Registry = localStorage  |
-| Unsaved    | Green 🟢    | Visible 🟡       | localStorage has changes |
-| After Save | Grey ⚪     | Hidden           | Auto-synced!             |
-| After AI   | Grey ⚪     | Hidden           | Auto-synced!             |
-
-## 🚀 Benefits
-
-1. **No confusion** - Visual state makes it obvious if you're synced
-2. **No manual work** - AI changes auto-save to registry
-3. **No stale data** - Version bumps auto-clear localStorage
-4. **No lost work** - localStorage still preserves edits during session
-5. **One-click fixes** - Reset button when things go wrong
-
-## 🎯 Best Practices
-
-**For Developers**:
-
-- Bump `version` when adding keyframes to existing compositions
-- Document breaking changes in description
-- Test auto-save flow after generating new compositions
-
-**For Users**:
-
-- 🟢 Green button = click to save your work
-- ⚪ Grey button = everything's synced, no action needed
-- 🟡 Orange badge = reminder you have unsaved changes
-- AI changes save automatically - no manual save needed!
-
----
-
-**Result**: Registry and localStorage stay in perfect sync with zero manual intervention! 🎉