# ISIS v2 WS07-004: Keyframe + Interpolation Flow Variants

## Scope

`WS07-004` implements reusable keyframe + interpolation flow variants for
controllable camera and character motion.

## Research and Existing Implementation Alignment

Implementation aligned with existing motion-control patterns:

- Camera-path keyframe concepts from
  `libs/isis/ai-video/src/advanced/video-generation-sota.ts`.
- Existing video workflow motion controls and easing metadata in the
  `libs/isis/workflows/src/workflows/video/*` catalog.

This task introduces a dedicated workflows-layer builder so keyframe motion
control is available as a typed reusable primitive for sequence tooling.

## Deliverables

1. Added keyframe interpolation flow builder module:

- `KeyframeInterpolationFlowBuilder`
- `createKeyframeInterpolationFlowBuilder`
- Typed camera/character keyframes, easing, variant profiles, samples, and
  output contracts.

2. Implemented interpolation and sampling engine:

- Supports `linear`, `ease_in`, `ease_out`, `ease_in_out`.
- Samples per-frame camera pose track and character motion track.
- Normalizes and clamps keyframes to sequence frame bounds.

3. Implemented flow variants for controllable motion:

- Default variant profiles: `camera-priority`, `character-priority`,
  `hybrid-balanced`.
- Applies configurable camera/character control weights per variant.
- Emits sequence-ready `requestParameters` including sampled motion tracks and
  control metadata.

4. Implemented deterministic fallback behavior:

- Uses static defaults when keyframes are omitted.
- Emits warnings when camera or character keyframes are missing.
- Enforces request contract validation (`shotId`, `frameCount`, `fps`).

5. Added unit test coverage:

- Variant generation with camera + character keyframes.
- Custom variant profile handling.
- Missing-keyframe fallback behavior.
- Invalid-contract rejection behavior.

6. Exported new APIs via package entrypoints:

- `libs/isis/workflows/src/templates/index.ts`
- `libs/isis/workflows/src/index.ts`

## Verification Commands

```bash
pnpm --filter @isis/workflows exec vitest run src/templates/keyframe-interpolation-flows.spec.ts src/templates/storyboard-shot-templates.spec.ts src/consistency/sequence-orchestration.spec.ts src/consistency/orchestration.spec.ts src/workflows.spec.ts
pnpm --filter @isis/workflows exec tsc -p tsconfig.json --noEmit
node scripts/isis/validate-v2-compliance-gate.mjs
```
