npm - @agent-native/core - Versions diffs - 0.85.7 → 0.86.1 - Mend

@agent-native/core 0.85.7 → 0.86.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1132) hide show

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

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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! 🎉