1 files changed, 204 insertions, 0 deletions
diff --git a/docs/keyframes.md b/docs/keyframes.md
new file mode 100644
index 00000000..97619626
--- /dev/null
+++ b/docs/keyframes.md
@@ -0,0 +1,204 @@
+# Keyframe System
+
+Keyframes allow element properties to change over time. The system is split into three layers: the **data model** (how keyframes are stored), the **registry** (which properties support keyframes and how to read/write them), and the **UI** (hooks and components that wire it all together).
+
+## How It Works
+
+### Data model
+
+Every `BaseTimelineElement` has an optional `animations?: ElementAnimations` field:
+
+```typescript
+interface ElementAnimations {
+    channels: Record<string, AnimationChannel | undefined>;
+}
+```
+
+A channel is a typed bucket of keyframes keyed by property path (e.g. `"opacity"`, `"background.color"`). Three channel types exist: `NumberAnimationChannel`, `ColorAnimationChannel`, and `DiscreteAnimationChannel`.
+
+### Registry
+
+`src/lib/animation/property-registry.ts` defines which property paths are animatable and how to read/write their values on an element. `src/types/animation.ts` holds the canonical list of valid paths in `ANIMATION_PROPERTY_PATHS`.
+
+### Resolver
+
+`src/lib/animation/resolve.ts` provides functions that return the effective value of a property at a given local time — falling back to the element's static value when no keyframes exist.
+
+### Renderer
+
+Nodes in `src/services/renderer/` call the resolve functions before drawing so that animated properties interpolate correctly during export and preview.
+
+### UI
+
+Two hooks in `src/components/editor/panels/properties/hooks/` handle the keyframe-aware field logic:
+
+- `useKeyframedNumberProperty` — for numeric fields (opacity, position, scale, etc.)
+- `useKeyframedColorProperty` — for color pickers
+
+Both hooks handle the toggle/add/remove keyframe flow and automatically switch between writing to the static property and writing to the animation channel depending on whether keyframes are active.
+
+---
+
+## Adding a New Animatable Property
+
+Using `"background.paddingX"` as an example.
+
+### 1. Register the path — `src/types/animation.ts`
+
+```typescript
+export const ANIMATION_PROPERTY_PATHS = [
+    // ...existing paths
+    "background.paddingX",
+] as const;
+```
+
+### 2. Add a registry entry — `src/lib/animation/property-registry.ts`
+
+```typescript
+"background.paddingX": {
+    valueKind: "number",          // "number" | "color" | "discrete"
+    defaultInterpolation: "linear",
+    numericRange: { min: 0 },     // optional, only for number properties
+    supportsElement: ({ element }) => element.type === "text",
+    getValue: ({ element }) =>
+        element.type === "text"
+            ? (element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX)
+            : null,
+    setValue: ({ element, value }) =>
+        element.type === "text"
+            ? { ...element, background: { ...element.background, paddingX: value as number } }
+            : element,
+},
+```
+
+**Notes:**
+- `getValue` must return the effective value including any defaults — this is what gets recorded when a keyframe is added.
+- `setValue` receives `AnimationValue` (`number | string | boolean`). Cast to the correct type since `coerceAnimationValueForProperty` already validated it upstream.
+- For color properties, use `valueKind: "color"` and cast `value as string`.
+
+### 3. Add a resolve function — `src/lib/animation/resolve.ts`
+
+For **numbers**, use the existing generic `resolveNumberAtTime`:
+
+```typescript
+import { resolveNumberAtTime } from "@/lib/animation";
+
+const resolvedPaddingX = resolveNumberAtTime({
+    baseValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+    animations: element.animations,
+    propertyPath: "background.paddingX",
+    localTime,
+});
+```
+
+For **colors**, use `resolveColorAtTime`:
+
+```typescript
+const resolvedColor = resolveColorAtTime({
+    baseColor: element.color,
+    animations: element.animations,
+    propertyPath: "color",
+    localTime,
+});
+```
+
+If neither fits (new value kind), add a dedicated resolve function following the same pattern as `resolveOpacityAtTime` and export it from `src/lib/animation/index.ts`.
+
+### 4. Wire the renderer
+
+In the relevant node (`src/services/renderer/nodes/`), call the resolve function before drawing:
+
+```typescript
+const resolvedPaddingX = resolveNumberAtTime({
+    baseValue: this.params.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+    animations: this.params.animations,
+    propertyPath: "background.paddingX",
+    localTime,
+});
+```
+
+Use the resolved value (not `this.params.*`) anywhere that value affects rendering.
+
+### 5. Wire the UI
+
+In the properties panel, replace `usePropertyDraft` with the appropriate keyframe hook and add a `KeyframeToggle` to the field.
+
+**For number fields:**
+
+```typescript
+const { localTime, isPlayheadWithinElementRange } = useElementPlayhead({
+    startTime: element.startTime,
+    duration: element.duration,
+});
+
+const resolvedPaddingX = resolveNumberAtTime({
+    baseValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+    animations: element.animations,
+    propertyPath: "background.paddingX",
+    localTime,
+});
+
+const paddingX = useKeyframedNumberProperty({
+    trackId,
+    elementId: element.id,
+    animations: element.animations,
+    propertyPath: "background.paddingX",
+    localTime,
+    isPlayheadWithinElementRange,
+    displayValue: Math.round(resolvedPaddingX).toString(),
+    parse: (input) => {
+        const parsed = parseFloat(input);
+        return Number.isNaN(parsed) ? null : Math.max(0, Math.round(parsed));
+    },
+    valueAtPlayhead: resolvedPaddingX,
+    buildBaseUpdates: ({ value }) => ({
+        background: { ...element.background, paddingX: value },
+    }),
+});
+```
+
+In JSX:
+
+```tsx
+<SectionField
+    label="Width"
+    beforeLabel={
+        <KeyframeToggle
+            isActive={paddingX.isKeyframedAtTime}
+            isDisabled={!isPlayheadWithinElementRange}
+            title="Toggle background width keyframe"
+            onToggle={paddingX.toggleKeyframe}
+        />
+    }
+>
+    <NumberField
+        value={paddingX.displayValue}
+        onFocus={paddingX.onFocus}
+        onChange={paddingX.onChange}
+        onBlur={paddingX.onBlur}
+        onScrub={paddingX.scrubTo}
+        onScrubEnd={paddingX.commitScrub}
+        onReset={() => paddingX.commitValue({ value: DEFAULT_TEXT_BACKGROUND.paddingX })}
+        isDefault={isPropertyAtDefault({
+            hasAnimatedKeyframes: paddingX.hasAnimatedKeyframes,
+            isPlayheadWithinElementRange,
+            resolvedValue: resolvedPaddingX,
+            staticValue: element.background.paddingX ?? DEFAULT_TEXT_BACKGROUND.paddingX,
+            defaultValue: DEFAULT_TEXT_BACKGROUND.paddingX,
+        })}
+    />
+</SectionField>
+```
+
+**For color fields**, use `useKeyframedColorProperty` instead. It returns `{ onChange, onChangeEnd, toggleKeyframe, isKeyframedAtTime }` — wire `onChange({ color })` and `onChangeEnd` directly to the `ColorPicker`.
+
+---
+
+## Checklist
+
+- [ ] Path added to `ANIMATION_PROPERTY_PATHS`
+- [ ] Registry entry added with correct `valueKind`, `supportsElement`, `getValue`, `setValue`
+- [ ] Resolve call added in the renderer node
+- [ ] UI field uses `useKeyframedNumberProperty` or `useKeyframedColorProperty` (not `usePropertyDraft`)
+- [ ] `KeyframeToggle` added to the `SectionField`
+- [ ] `onReset` calls `commitValue` (not `editor.timeline.updateElements` directly)